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The main purpose of this publication is to 
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programs compiled by the DOS PL/I 
Optimizing Compiler (Program Number 5736- 
PL1) are executed. It describes the 
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executable program phase, and the main 
storage situation throughout execution. 
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there are two appendixes: appendix A 
provides a diagrammatic summary of the 
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program execution; appendix B contains 
details of all control blocks that can 
exist during execution. 
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Processing a PL/I Program 



Figure 1.1 shows the processes through 
which a PL/I program passes from its 
inception to its use. There are four 
stages: 

1. Writing the program and preparing it 
for the computer. 

2. Compilation: translating the program 
into machine instructions (i.e., 
creating an object module) . 

3. Link-editing: producing an executable 
program phase from the object module. 
This includes linking the compiled 
code with PL/I library modules, data 
management routines, and possibly with 
other compiled programs. It also 
includes resolving addresses within 
the code. 

4. Execution: running the executable 
program phase. 

The process is not necessarily continuous. 
The program may, for example, be kept in 
either a compiled or link-edited form 
before it is executed, and it will normally 
be executed a number of times once 
compiled. 



COMPILATION 



Compilation is the process of translating a 
PL/I program into machine instructions. 
This is done by associating PL/I variables 
with addresses in storage and translating 
executable PL/I statements into a series of 
machine instructions. For example, the 
PL/I statements: 

DCL I,J,K; 
I=J+K; 

would typically result in the generation of 
machine instructions corresponding to the 
assembler language instructions shown 
below: 



LH 7,88(0,13) 
AH 7,90(0,13) 
STH 7,96(0,13) 



Load J into register 7 

Add K to J 

Place result in I 



The DOS PL/I Optimizing Compiler does 
not translate all PL/I statements directly 
into the necessary machine instructions. 
Instead, certain statements are translated 
into calls to standard subroutines held in 
the DOS PL/I Resident Library. Some of the 
resident library routines may, in turn, 
call further library routines from either 
the resident or the transient PL/I library. 
The following PL/I statements would, for 
example, result in a call being made to a 
resident library routine. 



DCL X,Y; 
X=SIN(Y) ; 



The code that would typically result from 
such statements is shown below: 



LA 14,92(0,13) 

LA 15,96(0,13) 

STH 14,15,80(0,3) 

LA 1,80(0,3) 

L 15,88(0,3) 



BALE 14,15 



Place address of Y 
in register 14. 
Place address of X 
in register 15. 
Place addresses in 
argument list. 
Point register 1 at 
argument list. 
Load register 15 
with the address of 
the resident library 
routine IBMBMGS. 
(This is held in the 
form of an address 
constant generated 
by the compiler and 
resolved by the 
linkage editor.) 
Branch to the 
library routine, 
which will carry out 
the reguired 
function. 



(The variables I, J, and K are held at 
offsets 96,88, and 90, respectively, from 
the address in register 13.) 



LINK- EDITING 



Link-editing links the compiler output with 
external modules that have been reguested 
by the compiled program. These will be 
PL/I resident library routines, data 
management routines, and, possibly, modules 
produced by further compilations. As well 
as linking the external modules, the 
linkage editor also resolves addresses. 
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EXECUTION 



The optimizing compiler produces code that 
requires a special arrangement of control 
blocks and registers for correct execution. 
This arrangement of control blocks and 
registers is known as the PL/I enyi ro nme nt. 
Execution consequently becomes a three- 
stage process: 

1. Setting-up the environment. This is 
handled by the PL/I initialization 
routines IBMDPIR and IBMDPII. 

2. Executing the program. 

3. Completing jobs after execution. This 
consists of closing any files that are 
left open and either returning control 
to the control program, with an EOJ 
macro instruction, or returning to a 
calling module. 



the executable program produced by the 
compiler. These features are: 

1. A communications area addressed by a 
dedicated register throughout the 
execution of the program. 

2. A scheme to handle dynamic storage 
allocation. 

3. The use of standard subroutines from 
the PL/I libraries, to handle such 
standard tasks as the housekeeping 
scheme and error handling. 

4. The use of an initialization routine 
to set up the communications area and 
initiate the housekeeping scheme. 

These features are discussed in greater 
detail below. 



Factors Affecting Implementation 



Three major factors influenced the design 
of the executable programs produced by the 
optimizing compiler. These factors are 
inherent in the language, and are: 

1 • The mod ula r structure qf.P L/I program s 

The PL/I language allows the 
programmer to divide his program into 
a series of blocks that can be written 
and compiled independently of each 
other. 

2 . The dy namic allo cat ion and freeing of 
storage 

Automatic, controlled, and based 
variables all have their storage 
allocated and freed dynamically. This 
implies a system of re-use of storage 
to reduce space requirements. 

3 • The comprehensive f acilities offered 
by the PL/I language 

The PL/I language offers more 
facilities than any other high-level 
language. These facilities include 
allowing the PL/I program to control 
the flow of execution after any PL/I 
interrupt. 



Key Features of the Executable Program 



Taken together, the factors outlined above 
are responsible for the main features of 



COMMUNICATIONS AREA 



The facilities offered by the PL/I 
language, particularly the error-handling 
facilities, imply that certain items must 
be accessible at all times during 
execution. To simplify accessing such 
items, a standard communications area is 
set up for the duration of execution. This 
area is known as the task communications 
area (TCA) , and is addressed by register 12 
throughout execution. 

The TCA has an appendage known as the 
task implementation appendage (TIA) . The 
TCA appendage holds a number of addressing 
fields and is, itself, addressed from the 
TCA. 



DYNAMIC STORAGE ALLOCATION 



The allocation and freeing of automatic 
storage on a block-by-block basis implies 
an automatic facility for the re-use of 
such storage. This problem and the problem 
of inter-block communication are solved by 
having, for each block, a save area that 
contains register save information, 
automatic variables, and housekeeping 
information. This area is known as a 
dynamic storage area (DSA) . It consists of 
the standard operating system save area 
concatenated with certain housekeeping 
information and with storage for automatic 
variables. DSAs are held contiguously in a 
last-in/first-out (LIFO) storage stack and 
are freed and allocated by the alteration 
of pointer values. 

On entry to a block, the registers of 
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Figure 1.2. Use of dynamic storage 
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the preceding block are stored in the 
previous DSA and a new DSA is acquired. A 
chainback pointer to the previous DSA is 
placed in the new DSA. This arrangement 
allows access to information in previous 
blocks. Register 13 is pointed at the head 
of the DSA for the current block. The code 
that carries out this and any other block 
initialization is known as a prologue. To 
obviate the need for special coding in the 
main procedure, a dummy DSA is set up by an 
initialization routine, and register 13 
points at this dummy DSA on entry to the 
main procedure. 

In addition to automatic variables, 
certain other types of storage are 
allocated and freed dynamically. Such items 
as are not freed on a last-in/ first-out 
basis are kept in a second stack. If 
storage within this stack is freed, it is 
placed on a free-area chain. The principles 
of the dynamic storage scheme are 
illustrated in figure 1.2. 

In certain circumstances, additional 
LIFO storage may be reguired during the 
execution of a block. When this is 
necessary storage is acquired in the same 
manner as for a DSA. The areas thus 
acquired are known as varia b le data areas 
(VDAs) . 

The storage scheme is handled partly by 
compiled code and partly by a resident- 
library routine. Compiled code acquires 
and frees space in the LIFO storage stack. 
LIFO storage is acquired by the proloque 
code of every block and freed by the 
epilogue code of every block. 

The library routine IBMDPGR is called 
when non-LIFO dynamic storage has to be 
allocated or freed, or when there is 
insufficient space for an allocation of 
LIFO storaqe in the LIFO stack. 



Resident Library and the DOS PL/I Transient 
Library. Transient library routines have 
the advantage of saving space, because they 
require storage only when they are actually 
in use and can be overwritten when they are 
no longer required. Resident library 
routines, however, have the advantage of 
speed, because they do not have to be 
loaded during execution of the PL/I 
program. Dividing subroutines into 
transient and resident types enables the 
compiler to balance the advantages of both 
types and so to produce programs that 
combine fast execution with reduced space 
overheads. 



INITIALIZATION ROUTINES 



The job of the initialization routines is 
to prepare a standard environment for all 
procedures compiled by the DOS PL/I 
Optimizing Compiler. This consists of 
setting-up the TCA and initializing the 
storage scheme. Also, a STXIT macro 
instruction is issued so that all program 
checks will be intercepted by the PL/I 
error-handling facilities. Using standard 
library routines for these tasks reduces 
the amount of special-case coding that is 
needed for a main procedure. A consequence 
is that procedures can be compiled and 
tested individually and then link-edited 
with other procedures and run without re- 
compilation. 



Contents of a Typical Executable 
Program Phase 



The contents of a typical executable 
program phase are shown in figure 1.3. 
contents are: 



The 



USE OF LIBRARY SUBROUTINES 



The use of library subroutines simplifies 
compilation. However, using such routines 
slows execution because they cannot be 
tailored for the particular situation in 
hand, and because they incur the overhead 
of saving and restoring registers. Library 
subroutines are used for handling standard 
jobs such as program initialization and 
error handling, and for such items as 
reguire interpretive code. Interpretive 
code is required when a significant part of 
the data will not be available until 
execution. 

Two PL/I libraries are used by the DOS 
PL/I Optimizing Compiler: the DOS PL/I 



1. Compiled code (the executable machine 
instructions that have been 
generated) . 

2. Link-edited routines. These will 
include resident library routines and 
probably DOS data management routines. 
Certain resident library routines are 
included in every executable program 
phase. These are the initialization 
routine, IBMDPIR, the storage-handling 
routine, IBMDPGR, and the error 
handler, IBHDERR. Other resident 
routines are included as required. 

As well as executable machine 
instructions, the program requires certain 
control information and addresses. Some of 
these are listed in fiqure 1.3, but full 
details are given in chapter 2. Other 
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Storage for any constants 
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Figure 1.3. Simplified diagram of an executable program phase 
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Figure 1.4. Use of storage 



control sections generated are also shown 
in figure 1.3. They are PLISTART, which 
passes control to the initialization 
routine, and PLIMAIN, which holds the 
address of the start of compiled code. 



The Overall Use of Storage 



The overall use of storage is illustrated 
in figure 1.4. As can be seen, the low- 
address end of the partition is occupied by 
the executable program phase. Immediately 
following the executable program phase is 
the program management area. This contains 
the control blocks set up by the 
initialization routines, including the TCA 
and the dummy DSA discussed above. The 
remainder of the partition is used for 
dynamic allocations of storage. The LIFO 
stack starts beyond the end of the program 
management area and expands, as necessary, 
towards the end of the partition. Non-LIFO 
dynamic storage starts at the end of the 
partition and expands towards the LIFO 
stack. 



The Process of Execution 



The process of execution is illustrated in 
figure 1.5. The processes involved for a 
sample program are described below. 

EXAMPLE: PROC OPTIONS (MAIN) ; 
INPUT: GET LIST(Y,Z) ; 



(process data as reguired) 



PUT LIST(X) ; 

IF X<500 THEN GO TO INPUT; 

END; 

Execution would involve the steps described 
below. 

1. The control program passes control to 
the control section PLISTART, which 
has been generated by the compiler. 

2. PLISTART calls the resident library 
initialization routine, IBMDPIR. 

3. IBMDPIR, and IBMDPII, which it calls, 
set up the PL/I environment. IBMDPIR 
then passes control to the main 
procedure compiled code, with register 
12 pointing at the TCA and register 13 
pointing at the dummy DSA. The 
address to which IBMDPIR passes 



PLISTART 



Receives control from 
system 

Passes control to 
initialization/ 
termination routine, 
IBMDPIR. 



Initialization routines 



Set up TCA, initialize storage and 
issue STXIT to initialize PL/I error- 
handling scheme. Pass control to 
the address in PLIMAIN. 



Prologue code 



Acquires DSA for main 
procedure, initializes 
control blocks, etc. 

Stores registers of 
initialization/ 
termination routine, 
IBMDPIR. 



Functional code 



Carries out function required 
in source program. This 
usually involves calls to 
library subroutines. 



Epilogue code 



Restores the registers of 
the initialization/ 
termination routine. 



Termination routine 



Closes any files still open and 
returns control to system with EOJ 
macro instruction, or returns 
control to caller. 



Figure 1.5. Flow of control during execution 



control is held in the control section 
PLIMAIN. 

4. Compiled code prologue stores the 
contents of the registers used by 
IBMDPIR in the dummy DSA and acguires 
a DSA for the main procedure. 

5. Compiled code calls the library 
routines used for stream I/O. These 
in turn call transient routines to 
open the standard files and further 
transient routines to interface with, 
and call, the link-edited data 
management routines. Storage must be 
acquired for transient routines and 
I/O buffers. This involves calling 
the storage management routine 
IBMDPGR. 

6. Processing is then carried out by 
compiled code. Further calls to the 
library may be involved if, for 
example, mathematical functions are 
used. 

7. The stream output will involve further 
steps similar to those described in 5, 
above. 



8. When the END statement is reached, the 
epilogue code is entered. This 
restores the registers of IBMDPIR and 
returns control to IBMDPIR. 



9. IBMDPIR raises the FINISH condition, 
calling the resident error-handling 
module IBMDERR, which searches for a 
FINISH on-unit. Finding none, it 
returns to IBMDPIR; IBMDPIR calls 
IBMDOCL to close the standard files 
SYSIN and SYSPRINT, which were opened 
to permit execution of the stream I/O 
statements. An EOJ macro instruction 
is then issued to terminate the 
program. 

This program illustrates the main points 
mentioned earlier in the chapter. The 
initi alization rout ines are used in steps 3 
and 9. The storag e ma n ag em ent scheme is 
illustrated in the prologue and epilogue 
code in steps 4 and 8. The communications 
area (TCA), is set up by the initialization 
routine, and the use of standard library 
subroutines is shown in steps 5 and 7. The 
use of specia l error and PL/I condition 
handling code is shown in step 9. 
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Chapter 2: Compiler Output 



Introduction 



The compiler output is a relocatable object 
module consisting of a series of records in 
card-image format. These records contain 
either machine instructions, constants, or 
external or internal addresses to be 
resolved by the linkage editor. The 
records are known as: 

TXT records containing machine 
instructions or constants. 

RLD records containing internal 
addresses. 

ESD records containing external 
addresses. 

Further information about the output passed 
to the linkage editor is given in the 
publication DOS P L/I Optimizing Compiler 
Program Logic . 

There are two main control sections 
(CSECTs) output by the compiler. These are: 

1. The program control section, holding 
the executable instructions translated 
from the PL/I program. 

2. The static internal control section 
holding constants, addresses, and 
static variables. 

A number of other control sections are 
also generated. These either handle certain 
housekeeping functions, or are used for 
external data which may have identical 
control sections generated for it by other 
compilations. 

Workspace and storage for automatic 
variables is acguired during execution, 
normally by the prologue code that is 
executed at the start of every block. 

The output from the compiler is shown in 
figure 2.1 and listed below: 

1 • Control sect ions that ar e alw ays 
g enerated 



Program control 
section 



Static internal 
control section 



Containing 
executable 
instructions. 

Containing 
addresses, control 
blocks, constants, 
and STATIC INTERNAL 



2. 



variables. 

PLISTART The entry point for 
the executable 
program phase. 
Passes control to 
initialization 
routine. 

Control sections that are generated 
only when reguired 

PLIMAIN Containing the 

address of the entry 
point of the main 
procedure. 
(Generated only for 
procedures with 
OPTIONS (MAIN) .) 

PLIFLOW A control section 

generated when the 
compiler FLOW option 
is specified. (See 
chapter 7.) 

PLICOUNT A control section 
generated when the 
compiler COUNT 
option is specified. 
(See chapter 7) . 

Static external A static external 
control sections control section is 
generated for every 
external variable, 
file, and procedure. 



Plus control 
sections for 



Each user-defined 
condition, and each 
compiler-generated 
subroutine used. 



The remainder of this chapter deals with 
these control sections in further detail. 
Where possible, it refers to the object 
program listing, because this is the form 
in which the output from the compiler is 
most readily available. 

The two control sections, PLISTART and 
PLIMAIN, are used during program 
initialization. PLISTART holds the address 
of the library initialization routine 
IBMDPIR, which will be entered at the start 
of the program. PLIMAIN holds the address 
of the start of the code for the main 
procedure. This is the address to which 
the library initialization routine branches 
when initialization is complete; it is 
marked "*REAL ENTRY" in the object-program 
listing. 
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Program control section 



COMPILER 



Housekeeping 
control sections 



PLISTART 
Contains: 

Instructions passing control to 

initialization routine 



PLIMAIN 
I Contains: 



r- 



Address of main procedure 



L. 



PLIFLOW 

Contains: 

External reference to library 
module used in FLOW option 



Control sections for 
compi ler-generated 
subroutines 




Contains: 

Executable instructions 
translated from source 
program 




Static internal control section 



Contains: 

Addresses 

Constants 

Control information 

Static internal 

variables 



L_ 



Control sections for 
data declared 
EXTERNAL 



A separate control section for each 
external: 

Variable 

File 

Procedure 

User condition 

Symbol table for external data 



_J 



I A control section for each 
I compiler-generated subroutine 
I used in a program 
I 



Control sections surrounded with dotted tines are generated only when required. 



Figure 2.1. Output from the compiler 
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A PLIMAIN control section is generated 
for every procedure for which OPTIONS 
(MAIN) is specified in the procedure 
statement. When two such procedures are 
being run together, control will always 
pass to the first of the procedures 
processed by the linkage editor. 

The format of PLIMAIN and PLISTART is 
given in appendix B. 

If the compiler FLOW option is being 
used, a control section called PLIFLOW is 
also generated. This contains code that 
results in the link-editing of the trace 
module IBMDEFL and also contains the values 
of "n" and "m" specified in the option. 
The format of PLIFLOW is given in chapter 
7. 

I 

|If the compiler COUNT option is in effect, 
ja control section called PLICOUNT is 
(generated. This contains code to link-edit 
| IBMDEFL. 



STATIC-STORAGE MAP 



The static-storage map is a formatted 
listing of the contents of the static 
internal and static external control 
sections. The static control sections 
contain items grouped in the following 
order: 

1. Address constants for entry points to 
procedures, and for branch 
instructions. 

2. Address constants for resident library 
subroutines. 

3. Address constants for addressing 
static storage beyond UK. 

4. The constants pool, which contains 
source program constants, data element 
descriptors, locator/descriptors, 
symbol tables, file control blocks, 
and other control blocks. 



The Organization of this Chapter 



The remainder of this chapter describes the 
contents of the static internal control 
section and the program control section* 
First, the conventions used in the object 
program listing and the static storage map 
are described. Descriptions of the two 
control sections follow. The description 
of the program control section covers the 
conventions used in the object program code 
such as register usage, method of handling 
flow of control, and addressing 
information. The chapter is completed by a 
short discussion of the effects of 
optimization. 



Listing Conventions 



Figure 2.2 shows the major program listing 
information that can be produced by the 
compiler. It also shows the relevant 
compiler options and summarizes the 
information that will be produced if these 
options are specified. Some or all of these 
options may be deleted at system generation 
time. To obtain deleted options, the 
correct password (specified at system 
generation time) must be specified in the 
CONTROL option. 

This chapter describes the contents of 
the static-storage map and the object- 
program listing. Information on the other 
items generated is given in the publication 
DOS PL/I Optimizing Compiler Programmer's 
Guide. 



5. Static variables. 

The constants pool and the static-variable 
sections of static storage begin on 
doubleword boundaries. 

The static control section is listed, 
each line comprising the following 
elements: 

1. Six-digit hexadecimal offset. 

2. Hexadecimal text, in 8-byte sections 
where possible. 

3. Comment, indicating the type of item 
to which the text refers; a comment 
appears against only the first line of 
the text for an item. A typical 
example is shown in figure 2.3. 

The following comments are used (xxx 
indicates the presence of an identifier) : 

A. . - Address constant. 

COMPILER LABEL CL.nn - Compiler-generated 
label. 

CONDITION CSECT - Control section for 
programmer-named condition 

CONSTANT 

CSECT FOR EXTERNAL VARIABLE - Control 
section for external variable. 

D. . - Descriptor. 

DED-. - Data element descriptor. 

DTF (CONSTANT PART) - Constant part of 
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Mane 



| Contents 



| Compiler Option 



Source program 
Aggregate table 

Storage requirements 

ESD references 

Statistics 

Static storage 

Variables offset map 



Table offset and 
statement number 

Object program 



Source program statements 

Names and storage requirements of structures 
and arrays 

Names and storage requirements of all 
procedures 

Name, type, and identifier of all external 
symbols generated by the compiler* 

Number of source records, program text 
statements, and object code bytes 

Contents of static internal and static 
external control sections in hexadecimal 
notation with comments 

The offset of static and automatic variables 
from this defining base 

Offsets, within code, of the start of all 
statements 

The contents of the program control section 
in hexadecimal and translated into a 
pseudo-assembler-language format 



SOURCE 
AGGREGATE 

STORAGE 

ESD 

ESD 



NAP 



MAP 



OFFSET 



LIST 



* External references within library modules are not included. 



Figure 2.2. Contents of listing and associated compiler options 



define-the-f ile (data management) 
control block. 

DTF (VARIABLE PART) - Variable part of 
define-the-f ile control block. 

ENVB - Environment control block. 

FCB - File control block. 

FED. . - Format element descriptor. 

KD.. - Key descriptor. 

ONCB - ON control block. 

PICTURED DED. . - Pictured DED. 

RD.. - Record descriptor. 

SYMTAB - Symbol table. 

USER LABEL xxx - Source program label xxx. 

xxx - Name of static variable. If the 

variable is not initialized, no text 
appears against the comment; there is 
also no static offset if the variable 
is an array. (The static offset can 
be calculated from the array 



descriptor if required.) 



OBJECT-PROGRAM LISTING 



By including the option LIST in the PROCESS 
statement, the programmer can obtain a 
listing of the compiled code, known as the 
object- program listing. It consists of the 
machine instructions plus an interpretation 
of these instructions in a form that 
resembles assembler language, and a number 
of comments such as the statement number. 
The format of this listing is shown in 
figure 2.4. As can be seen, blocks of code 
are headed by the number of the statement 
in the PL/I program to which they are 
equivalent. When optimization has resulted 
in code being moved out of a statement, 
this is indicated. Only executable 
statements appear in the listing. DECLARE 
statements are not included, because they 
have no direct machine-code equivalent. To 
simplify understanding of the listing, the 
names of PL/I variables are inserted, 
rather than the addresses that appear in 
the machine code. Special mnemonics are 
used when referring to control blocks and 
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PL/I OPTIMIZING COMPILER 



EXAMPLE: PROC OTIQNS (MAIN) REORCER; 



STATIC INTERNAL STORAGE MAP 



CCOOCO 


0000C098 


PROGRAM ACCOM 


000004 


00000008 


PROGRAM ACCON 


000008 


0000005A 


PROGRAM ACCON 


cooooc 


00000064 


PROGRAM AOCON 


OC0010 


00000064 


PRCGRAM ACCON 


000014 


00000000 


A..IELCGIA 


000018 


00000000 


A..IBMBCACA 


0000 1C 


00000000 


A..IBMBCE0B 


0COO20 


oocooooo 


A..IBMBCHFC 


000024 


00000000 


A..IBMBCTHC 


C00028 


00000000 


A..IBMBCVOY 


0000 2C 


OOCOOOOO 


A. .IBMBOCLA 


00003C 


OOCOOOOO 


A..IBMBOCLC 


000034 


00000000 


A..IBMBSEIA 


000038 


OOCOOOOO 


A..IBMBSICA 


00003C 


OOCOOOOO 


A..IBMBSXCA 


000O4C 


00000000 


A..IBMBSMWA 


000044 


00000000 


A..IBMBSEEA 


000048 


OOCOOOOO 


A..IBMBSEHA 


00004C 


ocoooooo 


A..IBMBSILA 


CC0050 


C8040680 


DEQ..X 


000054 


S00000030080 


FED 


OOOOSA 


60C0000B 


FED 


00005E 


58010000 


FED 


C00062 


OOOA 


CONSTANT 


000064 


0001 


CONSTANT 


OOC066 


0004 


CONSTANT 


C00068 


91EC91E0 


CONSTANT 


00006C 


OOCOOOOO 


CONSTANT 


CC0070 


46008000 


CONSTANT 


000074 


GOOCOOOO 


A..FCB 


0C007S 


OOCOOOOO 


A..FCB 


CC007C 


00000000 


A..FCB 


0CC08C 


80000000 


A.. TEMP 


000084 


00000000 


A..FCB 


000088 


80000000 


A. .TEMP 


0COC8C 






OC009C 


OOOOOOFC 00000064 


COMPILER LABE 



O0OC9C 
OOOOAO 
000CA8 
OCOCBC 
000CB4 



000004 
000C08 



000100 
000104 
000108 
0OO1OC 
OOOllO 
000114 
000118 
00011C 



STATIC EXTERNAL CSECTS 



CCOOOC OOOOOCCOOCOOOOOo 
OOCOOCOOOCOCOOOO 
0000007000000078 
O00OOOA800OCO0OO 



4040000001100000 

808C0C2O02C0O0OC 

0050E20000000050 

OOC0019800000198 

00000000004000E8 

COCOOOCCOOOOOOoo 

OOCC000000000050 

OOOCOOOOOOOOOOCO 

OOCOOCOOOOOOOOCO 

OOCOOOOCOOCCOOCC 

0005E2E8E2C9D51F 

OOC000000200009C 

010000A002CC009C 

0200009C0200009C 

02C0009C02COOOSC 

0200009C 

OOCOOOOO 

00000050 

C0C0800008000001 

C0000100 

OOOCOOOOooOOOOOO 

33C2E2E8E2C9D540 

4C0C0COOOOC0OOC0 

OOCOCB00002020F3 

800C0198 

800CCOOO0OCCOOO0 

COCOOOOOOOOCFFOO 

COCCCCOOOOCOOOCC 

1301002000CCOOCC 

00000050470000CO 

07CCOOE2 

40000006 

310000E4 

40C00005 

080C0108 

20000001 

06CC0198 

2000005005CCD858 

60C0007931C0D0B4 

40C0000508000DF8 

200000011ECCDECE 

3000008100000000 

OOOCOOOOCOCCOOCO 

COCOOOOOOOOOOCOO 

OOOCOOOOOOOOOOCO 

OOOCOCOOOOCOOOCO 

COCCOOOOOOOOOOOO 

OOCCOOOOOCCCOOCC 

0000000000000000 

OOCOOOCOOOOCOOOO 
OOOCOCOOOOCOOOCO 
0000000047FF001C 



ENVB CONSTANT 
ENVB CONSTANT 
DTF (CONSTANT PART) 
DTF (VARIABLE PART) 
DTF (CONSTANT PART) 



DTF (VARIABLE PART) 
DTF (CONSTANT PART) 



DTF (VARIABLE 
DTF (CONSTANT 
DTF (VARIABLE 
DTF (CONSTANT 
OTF (VARIABLE 
DTF (CONSTANT 
DTF (VARIABLE 
DTF (CONSTANT 



PART) 
PART) 
PART) 
PART) 
PART) 
PART) 
PART) 
PART) 



PL/I OPTIMIZING COMPILER 



EXAMPLE: PROC OTIONS (MAIN) RfcORCERi 





47FF001C 








OOOOCC 


COCOCCCCOOOCOOOO 
COOOOOCOOOCCOOOO 
000O00700000007C 
CO0O0CA8CC0C00O0 
4040000041201000 
8080CC2002000000 
0C79E2C0000C0079 
00000198000C0198 
OOOOOOCOOCOOOOOo 
COCOOCCCOOCCOOOO 
00CCO0COOO0C0078 
COCOOCCOOCCCOOOO 
OOCOOOCOOOOCOOOO 

oocoooooooocoooo 

0008E2E8E20709C9 
05E30000 


FCB 






00007C 


C0000000020000AO 


ENVB 






010000A4C20000AO 










020OO0AO02OCCOA0 










0200COA0020000AO 










O2O0OOA0 








OCOOAO 


00000000 


ENVB CONSTANT 




0000 A4 


00000079 


ENVB CONSTANT 




CC0OA8 


00008CC008000003 


OTF 


(CONSTANT 


PART) 


000080 


00000100 


DTF 


(VARIABLE 


PART) 


0OOOB4 


oocooocooooooooo 

3300E2E8E207C9C9 
05COOCCCOOOOOOOO 
00000600002020F3 


DTF 


(Constant 


PART) 


C000D4 


240CC198 


DTF 


(VARIABLE 


PART) 


000008 


80000CCOOOCOOOOO 
OOCOOOCOOOOCFFOO 
OOCOOOCOOOOCOOOO 
1300002000000000 
0000007947000000 


DTF 


(CONSTANT 


PART) 


0CO1CC 


C7000CE2 


DTF 


(VARIABLE 


PART) 


C00104 


40000006 


DTF 


(CONSTANT 


PART) 


000108 


310000E4 


DTF 


(VARIABLE 


PART) 


CC010C 


40C00005 


DTF 


(CONSTANT 


PART) 


00011c 


08000108 


DTF 


(VARIABLE 


PART ) 


000114 


20000001 


DTF 


(CONSTANT 


PARTI 


CC0118 


10000CF4 


DTF 


(VARIABLE 


PART) 


ccouc 


A0000008 


DTF 


(CONSTANT 


PART) 


C00120 


C5C00198 


DTF 


(VARIABLE 


PART) 


000124 


60000079 


DTF 


(CONSTANT 


PART) 


000128 


310000E4 


D T F 


(VARIABLE 


PART) 


00012C 


40000005 


DTF 


(CONSTANT 


PART) 


CC0130 


08000128 


OTF 


(VARIABLE 


PART) 


000134 


20C00001 


DTF 


(CONSTANT 


PART) 



COO 138 
000 13C 



lEOCona 

300C008100COOCCC 
OOOCOOOOOOOOOOCO 
COCCCOCOOOCCOOCC 
COOCCCOOOCCCOOCC 
COCCCOOOOOOOOOCO 
OCCCOOOOOOCCOOOO 
COCCCOCOOOOCOOCC 
COOOOOCOCOOCOCCO 
COCCOCOCOOCCOOCO 
COCCOCOOOOCOOOCO 
00CC000047FF0C1C 
47FF001C 



SOURCE LISTING 



STf.T LEV NT 



GET E0IT(XtY)(F(3) ,X(ll))i 

DO I = 1 TO Y; 

z»z*xm; 

END; 

put edit(zma): 
end: 



Figure 2. 3. Example of static storage map 
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PL/I OPTIMIZING COMPILER 



OBJECT LISTING 



EXAMPLE: PROC OTIDNS (MAIN 



* COMPILER 


GENERATED SUBROUTINE 


IELCGIA 




CCOOOO 


50 


EO 


1 


004 


ST 


14,4(0,1) 


C00004 


58 


FO 


1 


014 


L 


15,20(0,1) 


C00008 


D2 


03 


1 


01C D 04C 


MVC 


28(4,11,76(131 


CCOOOE 


91 


10 


1 


Oil 


TM 


l7(l),X«10' 


C00012 


47 


10 


7 


01A 


BO 


*+8 


000016 


96 


04 


C 


002 


01 


2(12),X'04> 


00001A 


C5 


01 


F 


050 E 002 


CLC 


80(2, 15), 2(14) 


000020 


47 


40 


7 


04E 


BL 


*+46 


000024 


91 


4C 


F 


02C 


TM 


44(15) ,X"tO' 


000026 


47 


80 


7 


03C 


BZ 


*+8 


C0002C 


96 


80 


1 


010 


01 


16(1), X'80' 


00003C 


48 


7C 


F 


050 


LH 


7,80(0,15) 


000034 


4B 


70 


E 


002 


SH 


7,2(0,14) 


000038 


40 


70 


F 


050 


STH 


7,80(0,15) 


C0003C 


58 


70 


F 


04C 


L 


7,76(0,15) 


CC0040 


50 


70 


1 


000 


ST 


7,0(0,1) 


000044 


4A 


70 


E 


002 


AH 


7,2(0,14) 


C00048 


50 


70 


F 


04C 


ST 


7,76(0,15) 


CC004C 


07 


F6 






BR 


6 


00004E 


58 


FO 


7 


064 


L 


15,1C0(C,7) 


C00052 


95 


60 


E 


000 


CLI 


0(14), X*60' 


000056 


47 


70 


7 


05E 


BNE 


*+8 


CCOOSA 


58 


FO 


7 


068 


L 


15,104(0,7) 


C0005E 


05 


EF 






BALR 


14,15 


OC0060 


07 


F6 






BR 


6 


C00062 


07 


00 






NOPR 





CC0064 










DC 


AL4(0) 


000068 










DC 


AL4(0) 



END OF COMPILER GENERATED SUBROUTINE 



* STATE 


:MENT NUMBER 


COOOOO 




C00007 




* PROCEDURE 


* REAL 


ENTRY 


C00008 


90 EC D OOC 


OCOOOC 


47 FO F 010 


0C0O10 


00000120 


C00014 


COCCOOOO 


0C0018 


58 3C F OOC 


OCOOIC 


58 10 04C 


000020 


58 00 F 008 


C00024 


IE Cl 


000026 


55 OC C OOC 



14,12,12(13) 

*+12 

F'288' 

A(STATIC CSECT) 

3,12(0,15) 

1,76(0,13) 

C, 8(0, 15) 

0,1 

0,12(0,12) 



:N) RECF 


:CER; 








00002A 


47 


CO 


F 


02C 


00002E 


58 


FC 


C 


074 


0OOC32 


05 


EF 






000C34 


58 


EO 


D 


048 


000C38 


18 


FO 






00OC3A 


90 


EC 


1 


048 


000C3E 


50 


00 


1 


004 


000C42 


41 


Cl 





OOC 


000 C46 


50 


50 





058 


000C4A 


92 


ec 





000 


000 04 E 


92 


20 


D 


001 


000052 


02 


03 


D 


054 


00OC58 


C5 


20 







* PROLOGUE BASE 

* INITIALISATION CODE FOR Z 
000C5A 78 40 3 06C 
C00C5E 70 40 D OAC 

* ENC Of INITIALISATION OlDE FOR 

000C62 05 20 

* PROCEDURE BASE 



* STATEMENT NUMBER 
000G64 41 40 D 0F8 
50 40 3 080 
96 60 3 080 
92 24 D 109 
41 EO 3 090 
50 EO C 110 
41 10 3 07C 
58 FO 3 04C 
05 EF 

41 AO 2 072 
48 EO 3 064 
50 EO D OEO 



000068 
000 C6C 
000070 
000C74 
000C78 
000C7C 
000C80 
000C84 
000C86 
000C8A 
000C8E 
00OC92 
000C92 
000C96 
00OC9A 
000C9E 
O00CA2 
000CA6 
OOOOAA 
OOOCAE 
OOOCBO 
000CB4 
O00CB8 
OOOCBC 



58 40 C OEO 
8B 40 002 
41 E4 D 0B4 
41 FO 3 050 
41 10 D 0F8 
50 10 C 0E4 
90 EF 1 008 
05 AA 

58 EC D OEO 
4A EO 3 064 
50 EC D OEO 
49 EO 3 062 



L 


15,116(0,12) 


BALR 


14,15 


L 


14,72(0,13) 


LR 


15,0 


STM 


14,0,72(1) 


ST 


13,4(0,1) 


LA 


13,0(1,0) 


ST 


5,88(0,13) 


MVI 


0( 13), X'80' 


MVI 


1(13), X'20' 


MVC 


84(4, 13), 104(3) 


BALR 


2,0 



BALR 2,0 



LA 


4,248(0,13) 


ST 


4,128(0,3) 


Cl 


128(3), X'80 1 


MVl 


265(13) ,X , 24 I 


LA 


14,144(0,3) 


ST 


14,272(0,13) 


LA 


1,124(0,3) 


L 


15.A..IBMBSILA 


BALR 


14,15 


LA 


10.CL.10 


LH 


14,10O(C,3) 


ST 


14,224(C,13) 


EQU 


* 


L 


4,224(0,13) 


SLA 


4,2 


LA 


14,VC..X(4) 


LA 


15.DE0..V0..X 


LA 


1,243(0,13) 


ST 


1,228(0,13) 


STM 


14,15,8(1) 


BALR 


10, 1C 


L 


14,224(0,13) 


AH 


14,1C0(C,3) 


ST 


14,224(C,13) 


CH 


14,98(0,3) 



PL/I OPTIMIZING COMPILER 



EXAMPLE: PROC DTIONS (MAIN) REORDER; 



CCOOCO 


47 


CO 


2 


02E 


C00OC4 


41 


EO 


D 


0A8 


C0OOC8 


41 


FO 


3 


050 


CCOOCC 


90 


EF 


1 


008 


OOOODO 


05 


AA 






CC00D2 


47 


FC 


2 


098 


CCC0D6 










C0C0D6 


41 


EO 


3 


054 


OOOODA 


58 


10 


D 


0E4 


OOOOOE 


50 


EO 


1 


004 


0C00E2 


58 


FC 


3 


044 


000OE6 


05 


EF 






CC00E8 


05 


AA 






OCOOEA 


41 


EO 


3 


05A 


OCOOEE 


58 


10 


C 


0E4 


00C0F2 


58 


70 


3 


014 


00COF6 


C5 


67 






CC00F8 


47 


FO 


2 


072 


OOOOFC 










* STATEMENT NUMBER 


COCOFC 


78 


00 


D 


0A8 


CCOIOC 


70 


00 





0E8 


CC0104 


48 


70 


3 


064 


C00108 


4C 


70 


D 


OBO 


C0010C 


48 


40 


D 


OBO 


CCOllC 


50 


40 


D 


0F8 


000114 


48 


40 


3 


070 


C00118 


40 


40 


D 


OF 8 


OCOllC 


97 


80 


D 


OFA 


000120 


78 


2C 





0F8 


0C0124 


7B 


2C 


3 


070 


CC0128 


70 


20 


D 


OEC 


C0012C 


39 


20 






OC012E 


47 


20 


2 


116 


000132 










* STATEMENT NUMBER 


0C0132 


48 


9C 


D 


oeo 


000136 


8B 


9C 





002 


00013A 


78 


40 





OAC 


C0013E 


7C 


49 





0B4 


000142 


70 


40 


D 


OAC 



* STATEMENT NUMBER 
0001*6 48 70 D °B0 
0CO14A 4A 70 3 064 
C0014E 40 70 D OBO 



BNH 


CL.5 


LA 


14, Y 


LA 


15.DED..Y 


STM 


14,15,8(11 


BALR 


10,10 


B 


CL.ll 


EQU 


* 


LA 


14,84(0,3) 


L 


1,228(0,13) 


ST 


14,4(0,1) 


L 


15,A..I£MBSEEA 


BALR 


14,15 


BALR 


10,10 


LA 


14,90(0,3) 


L 


1,228(0,131 


L 


7, A. .IELCGIA 


BALR 


6,7 


B 


CL.10 



LE 


c.v 




STE 


0,232(0. 


,13) 


LH 


7,100(0, 


i3) 


STH 


7,1 




LH 


4,1 




ST 


4,248(0, 


,13) 


LH 


4,112(0, 


,3) 


STH 


4,248(0, 


rl3) 


XI 


250(13), 


>X'80' 


LE 


2,248<0 


,131 


SE 


2,112(0, 


,3) 


STE 


2,236(0, 


, 13) 


CER 


2,0 




BH 


CL.3 





* CCDE 


*0VEC FROM STATEMENT 


NUMBER 4 






000152 


48 70 030 


LH 


7,1 




000156 


50 70 0F8 


ST 


7,248(0, 


,13) 


000 15A 


48 70 3 070 


LH 


7,112(0, 


,3) 


00015E 


40 70 D 0F8 


STH 


7,248(0, 


,13) 


000162 


97 80 D OFA 


XI 


250(13), 


,X'8, 


000166 


78 CO D 0F8 


LE 


0,248(0, 


,13) 


000 16A 


7B CO 3 070 


SE 


0,112(0, 


,3) 


000 16E 


70 CO OFO 


STE 


C, 240(0, 


,13) 


000172 


79 CO D 0E8 


CE 


0,232(0, 


,13) 



000176 47 CO 2 OCE 



fcNH CL.2 



* CCNTiKUATIDN OF STATEMENT NUMBER 
00017A CL.3 E 



» STATEMENT NUMBER 


C0017A 


41 


40 


D 


OFd 


00017E 


50 


4C 


3 


088 


000182 


96 


ec 


3 


088 


000186 


92 


20 


D 


109 


00018A 


41 


10 


3 


084 


00018E 


58 


FC 


3 


038 


000192 


05 


EF 






000194 


41 


AO 


2 


14 E 


000198 


41 


EO 


C 


OAC 


00019C 


41 


FO 


3 


050 


000 1A0 


41 


10 


D 


0F8 


000 1A4 


50 


10 


D 


0E4 


0001A8 


90 


EF 


1 


000 


0001AC 


05 


AA 






000 1AE 


47 


FO 


2 


166 


0001B2 










COO 182 


41 


EO 


3 


05E 


000 1B6 


58 


1C 


D 


0E4 


0001BA 


50 


EC 


1 


OOC 


0001BE 


58 


FO 


3 


048 


000 1C2 


05 


EF 






000 1C4 


05 


AA 






000 1C6 


47 


FO 


2 


14E 


000 1CA 










* STATEMENT NUMBER 


000 1CA 


18 


CD 






000 ICC 


58 


CO 


D 


004 


000100 


58 


EC 


D 


OOC 


0001D4 


98 


2C 


D 


01C 


000108 


05 


IE 






* ENO PROCECURE 




000 IDA 


07 


C7 







LA 


4,248(0,13) 


ST 


4,136(0,3) 


CI 


136(3) ,X'80" 


MVI 


265113) ,X'20' 


LA 


1,132(0,31 


L 


15.A..IBM8SI0A 


BALR 


14,15 


LA 


10.CL.7 


LA 


14, Z 


LA 


15, DEO. .Z 


LA 


1,243(0,13) 


ST 


1,228(0,13) 


STM 


14,15,0(11 


BALR 


10,10 


B 


CL.8 


EQU 


* 


LA 


14,94(0,3) 


L 


1,228(0,13) 


ST 


14,12(0,1) 


L 


15,A..leMBS£HA 


BALR 


14,15 


BALR 


10,10 



C13 

13,4(0,13) 
14,12(0,13) 
2,12,28(13) 



BALR 1,14 



Figure 2.4. Example of object program listing 
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other items. 



the begin block with label xxx. 



Statements in the object program listing 
are ordered by block. Statements in the 
outermost block are given first, followed 
by statements in the inner blocks. Thus 
the order of statements will frequently 
differ from that of the source program. 

Every object-program listing begins with 
the name of the procedure. The name is 
defined as a constant in a DC instruction. 
This is followed by another constant 
containing the length of the procedure 
name. Then comes the name of the 
procedure, as a comment, followed by code 
under the heading "REAL ENTRY." This is 
the point at which the code will, in fact, 
be entered. The second section of code is 
the prologue, which carries out various 
housekeeping tasks and is described more 
fully later in this chapter. The end of 
the prologue is marked by the message 
"PROCEDURE BASE." This is followed by a 
translation of the first executable 
statement in the PL/I source program. 

The comments used in the listing are as 
follows: 

* PROCEDURE xxx - identifies the start of 

the procedure labeled xxx. 

* REAL ENTRY xxx - heads the 

initialization code for an entry point 
to a procedure labeled xxx. 

* PROLOGUE BASE - identifies the start of 

the prologue code common to all entry 
points into that procedure. 

* PROCEDURE BASE - identifies the address 

loaded into the base register for the 
procedure. 

* STATEMENT LABEL xxx - identifies the 

position of source program statement 
label xxx 

* PROGRAM ADDRESSABILITY. REGION BASE - 

identifies address to which the 
program base is updated if program 
exceeds 4096 bytes and cannot be 
addressed from one base. 

* CONTINUATION OF PREVIOUS REGION - 

identifes the point at which 
addressing from the previous program 
base recommences. 

* END OF COMMON CODE - identifies the end 

of code used in the execution of more 
than one statement. 

* END PROCEDURE xxx - identifies the end 

of the procedure labeled xxx. 

* BEGIN BLOCK xxx - indicates the start of 



* END BLOCK xxx - indicates the end of the 

begin block with label xxx. 

* BEGIN BLOCK - GENERATED NAME BLOCK. nn - 

indicates the start of an unnamed 
begin block for which the compiler has 
generated the name BLOCK. nn, where nn 
is two hexadecimal digits. 

* END BLOCK. nn - indicates the end of the 

begin block with compiler-generated 
name BLOCK. nn. 

* STATEMENT NUMBER n - identifies the start 

of code generated for statement number 
n in the source listing. 

* INTERLANGUAGE PROCEDURE xxx - identifies 

the start of encompassing procedure 
xxx (see chapter 13) . 

* END INTERLANGUAGE PROCEDURE xxx - 

identifies the end of encompassing 
procedure xxx. 

* COMPILER GENERATED SUBROUTINE XXX - 

indicates the start of compiler- 
generated subroutine xxx. 

* END OF COMPILER GENERATED SUBROUTINE - 

indicates the end of the compiler- 
generated subroutine. 

* ON UNIT BLOCK - indicates the start of 

an on-unit block. 

* ON UNIT BLOCK END - indicates the end of 

the on-unit block. 

* END PROGRAM - indicates the end of the 

external procedure. 

* INITIALIZATION CODE FOR OPTIMIZED LOOP 

FOLLOWS - indicates that some of the 
following code has been moved from 
within a loop by the optimization 
process. 

* CODE MOVED FROM STATEMENT NUMBER n - 

indicates object code- moved by 
optimization to a different part of 
the program and gives the number of 
the statement from which it 
originated. 

* CALCULATION OF COMMONED EXPRESSION 

FOLLOWS - indicates that the value of 
an expression used more than once in 
the program is calculated at the point 
indicated. 

* METHOD OR ORDER OF CALCULATING 

EXPRESSIONS CHANGED - indicates that 
the order of the code following has 
been changed to optimize the object 
code. 
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In certain cases, mnemonics are used to 
identify the type of operand in an 
instruction, and, where applicable, this is 
followed by a source-program identifier. 
The following prefixes are used: 



A.. 
ADD.. 

BASE.. 

BLOCK. nn 

CL.nn 

D. . 
DED.. 

WSP.n 

L.. 

LOCATOR.. 

RKD.. 

VO.. 



Address constant. 

Aggregate descriptor 
descriptor. 

Base address of a 
variable. 

Label created for an 
otherwise unlabeled 
block. 

Compiler-generated 
label. 

Descriptor. 

Data element 
descriptor. 

Workspace, followed by 
decimal number of the 
block of allocated 
workspace. 

Length of variable. 

Locator. 

Record or key 
descriptor. 

Virtual origin (the 
address where element 
would be held for a 
one-dimensional array, 
element 0,0 for a 
two-dimensional array, 
etc.) . 



Static Internal Control Section 



The static internal control section 
contains the majority of items that are not 
executable instructions. The contents of a 
typical static control section are shown in 
figure 2.3. 

The first part of the static internal 
control section contains addresses. These 
are held in the order: 

1. Addresses of library modules 

2. Addresses of entry points 

3. Addresses of label constants that may 
be assigned to label variables 



4. Addresses of external procedures 
(other than library modules) 

The address section is followed by a 
section known as the constant s pool. This 
contains the following items (if required 
by the program) : 



Constants 



OMCBs 



Constant values used 
by compiled code. 

Control blocks used 
in error handling. 
(See chapter 7.) 



Descriptors, Control information 
locators and used by compiled 
DEDs (data element code and library, 
descriptors) (See chapter 4.) 

Symbol table Control information 
address vector and used in 
symbol tables data-directed I/O. 

(See chapter 4.) 



Diagnostic 
statement table 



Information on 
statement numbers. 



Items are arranged according to their 
alignment requirements, those requiring 
doubleword alignment first, followed by 
fullword, halfword, byte, and bit. 

The final section of the static internal 
control section holds the static variables. 
These are held in size order, smallest 
first: first the variables of 8 bytes or 
less, next the variables of 2048 bytes or 
less, and finally any variable greater than 
2048 bytes. This system ensures that the 
smallest possible number of items will 
require indirect addressing, since it will 
always be the largest variables that 
overflow the 4K boundary. Within each 
division, items are grouped according to 
alignment stringencies, starting with those 
requiring doubleword alignment. This 
method ensures optimum use of storage. 



Program Control Section 



The program control section contains the 
executable instructions that are a 
translation of the PL/I source program. 
The format of each program control section 
depends on the contents of the source 
program. The discussion that follows 
covers items that will be common to all 
source programs. 

To keep discussions of subjects as 
complete as possible the chapter also 
includes descriptions of certain library 
functions when they are closely allied with 
the subject under discussion. 
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r t 

| Dedicated | Work registers | Preferred registers | Notes | 
| registers | (plus special use) | I I 


r ~ ~ ~ ~ "" "*l 
| | | General | I Cannot be used | 
|| I I | as base | 


| 1 | | General + address | | I 
|| 1 of parameter list | I J 


| 2 | Address of | I I Saved during j 
| | program base | II in-line record | 
III | | I/O and TRT | 
|| | | | instructions | 


I 3 | Address of | I II 
| | static base | | I I 


| 4 | | Address of | I j 
|| | temporary base, | I I 
II 1 if DSA is j I I 
I | | larger than | I I 
I | I 3896 bytes | I I 


| 5 | | General + static | Preferred register | I 
| | | chainback on entry | for DO loop | I 
|| | to procedure | control variable | | 


I 6 | | General | I I 


I 7 | | General I I 1 


I 8 | | General | 1 1 


I 9 | | General | I 1 


| 10 | | General | Preferred registers for | I 


| 11 | | General | BXLE instruction is used | I 


| 12 | Address of TCA | II I 


| 13 | Address of | I II 
j | current DSA j I I I 


I 14 | | General + branch- | I I 


| 15 | ( and other routines | II 



Figure 2.5. Register usage in compiled code 



Register Usage 



Details of register usage during the 
execution of compiled code are given in 
figure 2.5. 

Four general registers are used as bases 
for addressing various types of data; these 
are known as dedicated registers. The 
remainder of the registers are used as they 
are required and are known as work 
reg isters 

Dedicated registers are: 



R2 Program base. 

R3 Static base. 

R12 TCA pointer. 

R13 DSA pointer. 

This arrangement of dedicated registers 
allows compiled code the use of six 
even/odd work register pairs. These are 
(0,1), (4,5), (6,7), (8,9), (10,11), and 
(14,15). 

Certain registers have special tasks for 
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which they are always used, or for which 
they are preferred and used when available. 
These tasks are shown in figure 2.5. 



general work registers for floating-point 
data. 



Dedicated Registers 



Register 2 - Progr a m Base Reg ister : 
Register 2 is the program base register and 
is used for branching within the code. 
When the code exceeds 4K, register 2 is 
updated so that all branching is done on 
this register. During in-line I/O (when 
data management calls are handled by 
compiled code rather than by library 
subroutines) , and during the execution of 
TRT instructions, the program base register 
contents are saved and the register used 
for other purposes. 

Register 3 - Static Base Reg iste r : 
Register 3 points to the start of the 
static internal control section. The items 
to be found in this control section in any 
particular program are listed in the 
static-storage map put out by the compiler. 
(See "Static Internal Control Section," 
later in this chapter.) When the static 
control section is larger than 4K bytes, a 
further base register is used. 

Register 12,7 TCA: Offsets from register 
12 are used to address the various fields 
in the TCA. The TCA is discussed further in 
chapter 5 and appendix B. 

Register 13 - Curre nt PS A; Register 13 
points to the current DSA and is used to 
address the automatic variables declared in 
the current procedure or block. References 
to offsets from register 13 which do not 
appear as names in the assembler language 
listing are references to the housekeeping 
fields held in every DSA or to temporaries. 
These are discussed in chapter 6; a map of 
the housekeeping information in a DSA is 
given in appendix B. 



Work Registers 



Special or preferred uses for work 
registers are shown in figure 2.5. Special 
uses are those for which the register is 
freed and always used. Preferred uses are 
those for which the register is used when 
possible. 



Library Register Osage 



Register usage in library modules is 
different from that in compiled code. It is 
shown in figure 2.6. 



Register | 



Osage 



Floating-Point Registers 



Floating-point registers are all used as 



1 | Work register 

2 | Work register 

3 | Program base register 
| (dedicated) 

4 | Work register 

5 | Work register 

6 | Work register 

7 | Work register 

8 | Work register 

9 j Work register 

10 j Work register 

1 1 | Work register 

12 | TCA pointer (dedicated in 
j both library and compiled 
| code) 

13 | DSA pointer 

14 | Work register (always used 

I for branch-and-link to other 

| routines) 

15 | Work register (used with 
| register 14 for 

j branch-and-link) 



Figure 2.6. Library register usage 

Two further points about library 
register usage are worth noting: 

1. Registers 14 through 4 are normally 
saved by the library. This is because 
the majority of library subroutines 
use only these registers. 
Conseguently, time can be saved by 
reducing save-restore requirements. 
However, some library routines also 
save one or more of registers 5 
through 11. 

2. The majority of library subroutines 
require argument lists that are 
addressed by register 1. However, 
certain library routines have their 
parameters/arguments passed directly 
in registers. The registers used for 
this purpose are 1, 5, 6, and 7. 



Handling and Addressing Variables 



COMPILER-GENERATED TEMPORARIES 



HANDLING AUTOMATIC VARIABLES 



Automatic variables have storage allocated 
on a procedure or begin-blockj basis. 
Variables whose length is known during 
compilation have storage allocated within 
the DSA of the block in which they are 
declared. Variables whose length is not 
known until execution time have their 
storage allocated in variable data areas 
(VDAs) . VDAs are held in the last-in/first- 
out storage stack and are acguired in the 
prologue code after the DSA has been 
acguired. The same method is used as is 
used for acquiring the DSA (see above under 
"Prologue Code.") 

Automatic variables when used in the 
block in which they are declared are 
addressed from register 13, if they are 
held in the DSA. If they are held in a 
VDA r a separate base is set up for the VDA 
and they are addressed from this. 

Within a DSA r automatic variables are 
held in size order. First those of 8 bytes 
or less, then those of 2048 bytes or less, 
and finally those larger than 2048 bytes. 
Within each group items are held in 
alignment stringency starting with items 
that reguire doubleword alignment. This 
arrangement results in the minimum number 
of variables overflowing the 4096 byte 
addressing boundary. The contents of a 
typical compiled code DSA are shown in 
figure 2.7. 

Automatic variables known in any 
procedure or block are those that are 
declared in that procedure or block, or in 
any encompassing procedures or blocks. The 
method used to address automatic variables 
in outer blocks is as follows. The address 
of the DSA of the block in which the 
required variable was declared is placed in 
the current DSA. This address can then be 
accessed from register 13. This is done in 
the prologue. (Frequently, the value is 
retained in the register used in the 
initial load and not reloaded when the 
variable is accessed.) Typical code would 
be 

L 7,96(0,13) Pick up address of 
correct DSA 

L 8,108(7) Place value of variable 
in register 8 



Because PL/I statements can contain an 
unlimited number of operands, it is 
frequently necessary to set up fields 
containing intermediate results. These 
fields are known as tempora ry variables 
(temporaries) and are allocated within the 
DSA of the associated block, provided that 
the size of storage required is known at 
compile time. To simplify addressing the 
temporaries, register 4 is used to point at 
the start of the area used for storing 
them, if the DSA requires more than 30896 
bytes of storage. 

Because temporary storage is continually 
being reused, the same storage area will 
not always hold the same temporary. 



Temporaries for Ad justable V ariables 



Where a temporary is needed to hold a value 
for an adjustable variable, its size is not 
predictable until execution. In such 
cases, a VDA is acquired for the temporary 
value. 



CONTROLLED VARIABLES 



Controlled variables are addressed throuqh 
a field that holds the address of the most 
recent allocation of the variable. For 
internal controlled variables, this address 
is held in the static internal control 
section. For external controlled 
variables, a separate control section is 
qenerated. When no allocations of the 
controlled variable have been made, the 
address field is set to zero. 

Each allocation of a controlled variable 
holds the address of the previous 
allocation in a chainback field at its 
head. For the first allocation, the 
chainback field is set to zero. 

The stacking and unstacking of 
controlled variables is handled by the 
library module IBMBPAF. This, in turn, 
makes use of IBMDPGR to actually allocate 
or free the storage for the variables. 



Control Block 



The control block area at the head of each 
controlled variable is four words in length 
and consists of the following fields. 



Chapter 2: Compiler Output 19 



R13 



Housekeeping information 

See appendix A 



Items < 9 bytes in length 

Held in alignment order: 
doubleword 
fullword 
halfword 
byte 
bit 



Items 9 - 2048 bytes in length 

Held in alignment order as above 



Items > 2048 bytes 

Held in alignment order as above 



Parameter storage area 

Addresses of any parameters 
passed to the associated 
procedure are stored here 



Register bind storage area 

Used by compiled code when 
registers must be saved 



Local temporary storage 

Used for temporaries required 
for duration of statement 



Global temporary storage 

Used by temporaries required 
for duration of block 



Storage for automatic 
variables declared in 
the block, dynamic 
ONCBsetc. 



Temporary storage 



Figure 2.7. Typical contents of a compiled code DSA 
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Word 1 The first word is used for 
chaining. 

Word 2 Word 2 contains the length of the 

variable, including the control block. 

Word 3 Word 3 points to the address of the 
previously allocated variable, or 
contains zero if there is none. (This 
address is word 5 of the area used by 
the previous allocation, because the 
address is that of the start of the 
variable itself rather than the 
control block.) 

Word 4 Word 4 is unused. 



class. 

When a based variable is allocated, a 
call to the storage management module 
IBMDPGR is made. IBMDPGR acquires storage 
in the non-LIFO dynamic storage area and 
returns the address of the storage in 
register 1. The address held in register 1 
is then placed in the pointer on which the 
allocated variable is based. 

When the variable is freed, a further 
call to IBMDPGR is made to free the 
storage. (Details of the functions of 
IBMDPGR are given in chapter 6.) 

Pointers : Pointers are held as fullwords. 
The null pointer value is X'FFOOOOOO 1 . 



Allocating a V ariable 



A controlled variable is allocated when 
IBMBPAF is entered by entry point A. The 
length of the storage required and the 
address of the anchor word which will hold 
the address of the current invocation are 
passed in register 1. The length is 
increased by 16 bytes to allow for the 
control block, and the module IBMDPGE 
called to allocate the storage. The 
control block is then initialized. The 
first bit in the anchor word is set to 
indicate that the controlled variable has 
been allocated, the old address in the 
anchor word having been set in the 
chainback field (word 3) in the control 
block at the start of the variable. If 
there have been no previous allocations, 
this address is zero. 



Freei ng a Controlled Variabl e 



Freeing a controlled variable is carried 
out by IBMBPAF when entered via entry point 
B. The address of the anchor word is 
passed by compiled code. If the chainback 
field in the variable is zero, the first 
bit of the anchor word is set on, and the 
area freed by calling IBMDPGR. 

If the chainback field is not zero, the 
address in the chainback field is placed in 
the anchor word, and IBMDPGR called to free 
the area* 



BASED VARIABLES 



Based variables are addressed by using the 
contents of the pointer on which they are 
based. The pointer is addressed in the 
usual manner, depending on its storage 



STATIC VARIABLES 



Static internal variables are held in the 
static internal control section and are 
addressed from register 3. 

Static external variables are held in 
separate control sections and are addressed 
from an address constant in the static 
internal control section. 



ADDRESSING BEYOND THE 4K LIMIT 



As described above, variables and 
temporaries can, in the simplest case, be 
addressed by using an offset from one of 
the base registers. However, as the space 
reguired for any particular type of storage 
can exceed the maximum offset allowed in 
addressing (4096 bytes), it is necessary to 
have a scheme to allow addressing of 
variables beyond this limit. 

The method used is to divide storage for 
automatic variables, temporaries, and 
static variables into sections of 4096 
bytes. The addresses of the second and 
subsequent sections are then placed in the 
first section. Addressing of an automatic 
variable beyond the 4096-byte limit is 
typically done by code resembling the 
following: 



L 6,92(0,13) 



AH 7,96(0,6) 



Place address of 4K 
boundary in register 6. 

Address variable by using 
offset from 4K boundary 
placed in register set 
up in last instruction. 



A similar system is used for addressing 
any static variables and temporaries which 
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are at an offset greater than 4096 bytes. 
The addresses are held in the following 
areas: 

Automatic Immediately following the 
housekeeping information 
of the DSA. 

Static At the head of the first 
section of static 
storage. 

Temporaries At the head of temporary 
storage, following bases 
of parameters, register 
save area, and addresses 
of any outer DSAs. 

Constants and variables are held in 
order of size, with the smallest first. 
This minimizes the number of items that 
overflow the 4K boundary. 



Array descriptors are described in chapter 
4. 

Structures are treated in a similar 
manner. Where all information about a 
structure is known, it is mapped during 
compilation and offsets to each item from 
the start of the structure are known to 
compiled code. If a structure cannot be 
mapped during compilation, it is mapped 
during execution, and the offsets within 
the structure are placed in a control block 
known as a structu re desc ripto r. To access 
an item in the structure, compiled code 
finds the offsets and calculates the 
address of each element from them. 
Structure descriptors and the process of 
mapping during execution are described in 
chapter 4. 



Handling Data Aggregates 



PL/I data aggregates are structures and 
arrays. This includes both arrays of 
structures and structures of arrays. 

Array elements are addressed from the 
virtual origin of an array. This is the 
point at which the element whose subscripts 
are all zeros is held, or would be held if 
no such element is included in the array. 
Each element can be accessed by using a 
multiplier for each dimension. The 
multiplier is the distance between elements 
in a cross-section of an array. For 
example, in an array B(9,9) the multiplier 
for the first dimension is the distance 
between elements B(1,1) and B(2,1); the 
multiplier for the second dimension is the 
distance between elements B(1,1) and 
B(1,2). 

If the bounds of the array and the 
length of the elements of the array are 
known during compilation, the values of 
multipliers can be calculated and placed as 
constants in the static internal control 
section. For accessing an element with a 
constant subscript, the offset from the 
virtual origin can be calculated during 
compilation. If the subscript value is a 
variable, the multiplier must be picked up 
from static storage during execution and 
the value calculated. 

If the bounds or extents of an array are 
not known during compilation, a control 
block known as an array d escriptor is set 
up. This control block is used to hold 
necessary information about bounds, 
multipliers, etc. The information is placed 
in the control block during execution. 



ARRAYS OF STRUCTURES AND STRUCTURES OF 
ARRAYS 



Arrays of structures and structures of 
arrays are held as they are declared. 

The array of structures 



S(2), 



B, 

c; 



would be held in the order S(1).B, S(1).C, 
S(2).B, S(2).C. 

B and C are known as interleaved array s, 
because the elements within each array are 
not contiguous. 

The structure of arrays 

S, 

B(2) 

C(2); 

would be held in the order S.B(1), S.-B(2), 
S.C(1) , S.C(2) . 

Elements are accessed as array elements in 
both cases. In the array of structures 
shown above, both B and C are treated as 
separate arrays with their own virtual 
origins and multipliers. When possible, 
the values of multipliers are calculated 
during compilation. When adjustable bounds 
or extents are involved, the necessary data 
for both arrays of structures and 
structures of arrays is placed in a 
structure descriptor (see chapter 4) . 
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ARRAY AND STRUCTURE ASSIGNMENTS 



Assignments between structures and arrays 
of the same format are done by MVC 
instructions. Provided an array is not 
interleaved, an assignment will be made to 
it as a whole, and the elements will not be 
moved one at a time. Similarly, structures 
that are contiguous and have the same 
format are moved as a whole. 



Handling Flow of Control 



In PL/I, five types of statement can result 
in non-consecutive flow of control. These 
statements are: 

CALL statements 

END statements 



instruction on registers 14 and 15. Within 
the prologue code, the registers are stored 
in the DSA of the calling block, and a new 
DSA is set up to hold the automatic 
variables of the new block plus a certain 
amount of environmental information such as 
the enablement or disablement of certain 
conditions. 

When a block is terminated, the 
registers of the calling block are 
restored, and a branch is made on register 
14. This immediately returns control to the 
instruction after the BALR issued in the 
preceding block. The DSA of the called 
block is automatically discarded because 
all fields in the DSA, including the 
pointer to the next available byte of free 
storage, were addressed from register 13. 
Because register 13 has been altered, the 
values that apply to the calling block 
automatically become current when the 
calling blocks registers are restored. 



RETURN statements 
Function references 



PROLOGUE AND EPILOGUE CODE 



GOTO statements 

The first four of these are concerned with 
the block structure of the PL/I program and 
involve passing control from one block to 
another. GOTO statements can result in 
branches to code that is either in the 
current block, or in any other active 
block. 

Consecutive flow of control also ceases 
when an error or program interrupt occurs. 
The methods used to handle error and PL/I 
condition situations are described in 
chapter 7, "Error Handling." 



Every PL/I begin block or procedure block 
has prologue and epilogue code. The 
prologue prepares the environment for the 
associated block and acquires storage for 
automatic variables, compiler-generated 
temporaries, and workspace. The epilogue 
frees the storage acquired for the block, 
restores the environment of the calling 
block, and returns control to the calling 
block. 



Prologue 



ACTIVATING AND TERMINATING BLOCKS 



CALL, END, and RETURN statements, and 
function references, all result in the 
activation or termination of blocks. The 
block structure of PL/I, as explained in 
chapter 1, is implemented by means of a 
hierarchy of DSAs. 

Each block (begin block, procedure 
block, or on-unit block) executes on its 
own program base that is set up at the end 
of the prologue code for each block. This 
base is marked in the object code listing 
with: 

* PROCEDURE BASE 

In the PL/I optimizing compiler, blocks 
are always called by means of a BALR 



The prologue a 
listing betwee 
PROCEDURE BASE 
prologue has t 
(DSA) for the 
register save 
housekeeping i 
automatic vari 
jobs that may 
are: 



ppears on the object-program 
n REAL ENTRY and either 

or BLOCK BASE. Every 
o acquire a dynamic save area 
new block. (The DSA is a 
area concatenated with 
nformation, plus storage for 
ables and temporaries.) Other 
be done in the prologue code 



Initialization of automatic variables 
that have the INITIAL attribute. 

Initialization of pointers and locators 
that have the INITIAL attribute. 

Movement of parameter addresses passed 
to the procedure to the correct 
location. 

Acquisition of storage for adjustable 
variables. 
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STM 


14,12,12(13) 


BC 


*+ 16 


DC 


A(STMT NO TABLE) 


DC 


F'272» 


DC 


A (STATIC CSECT) 


L 


3,16(0,15) 


L 


1,76(0,13) 


L 


0,12(0,15) 


ALR 


0,1 


CL 


0,12(0,12) 


BNH 


*+10 


L 


15,116(0,12) 


BALE 


14,15 


L 


14,72(0,3) 


LB 


15,0 


STM 


14,0,72(1) 


ST 


13,4(0,1) 


LA 


13,0(1,0) 


ST 


5,88(0,13) 


MVI 


0(13),X»80» ( 


MVI 


1(13),X»00« ( 


MVC 


84(4,13) ,166(3) 



Other code as required 



BALB 



2,0 



Store registers of calling program. 

Branch around constants. 

Constant - address of statement number table. 

Constant - length reguired for new DSA. 

Constant - address of static internal CSECT filled in 

by linkage editor. 

Set up R3 as static base. 

Set B1 to old NAB (start of new DSA). 

Place length reguired for new DSA in R0. 

Add old NAB (in R1) and length required for DSA (in 

B0). 

Compare with EOS in TCA. 

Branch around library call if new DSA fits segment. 

Load address of stack overflow routine (IBMBPGRC) from 

TCA. 

Branch to overflow routine. 

Pick up library workspace address. 

Place NAB address in R15. 

Store library workspace address and current and 

end-of -prologue NAB addresses in new DSA. 

Set up backchain to previous DSA. 

Point R13 at new DSA. 

Set up static backchain. 

Set up housekeeping flags - see appendix B. 

Set up enable cells - see chapter 7. 

Other tasks may be carried out at this point. (Such 
as, initialization of variables with the initial 
attribute, acquiring a VDA for adjustable variables, 
and setting up certain error-handling fields.) 
Set B2 as program base. 



Figure 2.8. Typical prologue code 



in register 5. 



I L 

| LM 

I 

| BE 14 



13,4(0,13) 
14,12,12(13) 



Chainback | 

Bestore registers of | 
preceding block j 

Beturn j 

— . j 



Figure 2.9. Epilogue code 

• Initialization of certain items for 
argument lists. 



Static backchains are used in tracing 
the scope of names and the enablement of 
PL/I conditions. 

For PL/I procedures with COBOL or 
FOBTBAN in the OPTIONS option, the prologue 
is considerably different. See chapter 13, 
"Interlanguage Communication." 



2.7, 



The format of the DSA is shown in figure 



Setting-up certain interrupt-handling 
information such as ONCBs and enable 
cells. (See chapter 7.) 



An example of prologue code is shown in 
figure 2.8. 

Two backchains are set up. The dynamic 
backchai n, which points to the DSA of the 
calling or preceding block, and the static 
backchain, which points to the DSA of the 
statically encompassing block. For the 
main procedure, the dynamic backchain 
points to the dummy DSA, and the static 
backchain is set to zero. The address of 
the statically encompassing block is passed 



Epilogue code comprises the instructions 
generated for END or RETURN statements. 
These instructions restore the registers to 
the values that were held when the current 
block was called. The register values are 
those stored in the previous DSA. Typical 
epilogue code is shown in figure 2.9. 

For the external procedure the epilogue 
code is slightly different. The address of 
the current DSA is saved in register 0, and 
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return made by a BALR instruction using 
registers 1 and 14. This allows return to 
the program if a FINISH on-unit has to be 
executed. 



ILL Statements 



CALL statements are executed by picking up 
the address of the block to be called from 
static storage. A BALR instruction is then 
carried out on registers 14 and 15. If 
arguments are being passed to the called 
procedure, an argument list is set up in 
temporary storage, the .first bit of the 
last argument is set to • 1 » , and register ' 
is pointed at the argument list. Typical 
code would be: 



LR 5,13 

Load static backchain 

address 

L 15,A...X 

Pick up address of 

procedure X 

BALR 14,15 

Branch to procedure 



00031A 18 5D 



00031C 58 FO 3 020 



000320 05 EF 



Function References 



Function references are compiled in exactly 
the same way as CALL statements. If the 
function returns a value, an extra field is 
placed as the last argument in the list. 
The returned value is placed in this field 
when the function is completed. Typical 
code would be: 



9,B 

9,188(0,3) 

9, A 

9,192(0,3) 
Set up parameter list 
LR 5,13 

Load static backchain 
address 

LA 1,188(0,3) 
Point register 1 
at parameter list 
L 15, A... DOUBLE 
Place address of 
function 
(DOUBLE) in R15 
BALR 14,15 
Branch to function 



000 1FE 


41 


90 


6 


0B4 


LA 


000202 


50 


90 


3 


0BC 


ST 


000206 


41 


90 


6 


0B0 


LA 


00020A 


50 


90 


3 


OCO 


ST 



00020E 18 5D 



000210 41 10 3 0BC 



000214 58 F0 3 008 



000218 05 EF 



END Statement 



block and branching to the value held in 
register 14 of that block. 

Code compiled for an END statement of an 
internal block takes the following form: 



000402 58 DO D 004 
000406 98 EC D 00C 
00040A 07 FE 



L 13,4(0,13) 

Pick up DSA backchain 

LM 14,12,12(13) 

Restore registers 

BR 14 

Branch to procedure 



For main procedures, certain further 
actions have to be taken. Because the end 
of a main procedure raises the FINISH 
condition, it is necessary to save the 
current value of register 13 so that the 
error handler may search the DSA chain for 
a FINISH on-unit. As it is possible to 
reguest a SNAP trace in a FINISH on-unit, 
it is also necessary to save the address of 
the END statement. For this reason, the 
branch is made with a BALR instruction 
rather than a branch instruction as used 
for internal blocks. Typical code would 
be: 



00188C 18 0D 



00188E 58 DO D 004 



001892 58 EO D 00C 



001896 98 2C D 01C 



00189A 05 1E 



LR 0,13 
Save current DSA 
address in R0 
L 13,4(0,13) 
Pick up DSA backchain 
L 14,12(0,13) 
Restore register 14 
LM 2,12,28(13) 
Restore registers 2 
through 12 
BALR 1,14 

Branch to initializa- 
tion routine saving 
branch address in 
register 1 



RETURN Statement 



RETURN statements are executed in a similar 
way to END statements, but result in the 
termination of a procedure rather than a 
block. Consequently, before the 
restoration of the registers, a chainback 
must be made to the correct DSA. A 
chainback is made through any begin blocks. 
The depth of nesting can be determined 
during compilation, so the backchain can be 
loaded the required number of times before 
the branch is made. Typical code would be: 



END statements result basically in 
restoring the registers of the calling 



0003EC 


58 


DO 


D 


004 


L 13,4(0,13) 


0003F0 


58 


DO 


D 


004 


L 13,4(0,13) 

Pick up DSA backchain 


0003F4 


98 


EC 


D 


OOC 


LM 14,12,12(13) 
Restore registers 


0003F8 


07 


FE 






BR 14 

Branch to procedure 
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Note: If the procedure in which the RETURN 
statement occurs is a main procedure, the 
code will take the form compiled for an END 
statement for an external procedure (see 
above) . 



same format as a label variable, consisting 
of the address of the label constant 
followed by the address of the associated 
DSA. 



GOTO STATEMENTS 



GOTO Within a Block 



The implications of a GOTO statement depend 
on whether the label branched to is within 
the block or external to it. If the label 
is outside the block, the branch implies 
that one or more blocks must be terminated. 
If the label in the GOTO statement is a 
label variable, it is not always possible 
to determine during compilation whether the 
label will be in the same block as the GOTO 
statement. Consequently, interpretive code 
is used for label variables. 

For GOTO statements to a label constant 
within the block, the compiler produces a 
straightforward branch instruction. For 
GOTO statements that may pass control to 
another block, compiled code calls the 
interpretive code in the TCA. 

Interpretive code to handle a GOTO out 
of block is held in the TCA. To implement 
a GOTO that will or may transfer control 
out of the block, compiled code branches to 
code in the TCA. The code in the TCA 
checks to see whether it is one of a small 
number of special cases, and, if it is, 
calls a subroutine of the PL/I resident 
library module IBMDPIR. IBMDPIR is the 
program initialization routine and is 
always link-edited. In other 
circumstances, the GOTO code in the TCA 
handles the branch and any block 
termination involved. 

The special cases all occur when 
executing code handled by library modules. 
These library modules flag the TCA and 
their own DSA to indicate that special 
action must be taken when a GOTO occurs. 

To execute a GOTO statement, three 
things must be known: 

1. The address of the instruction to be 
branched to. 

2. The address of the program base. 

3. The address Of the DSA associated with 
the instruction. 

The label constant holds items 1 and 2. 
Item three is held in a label variable. 
(For formats see appendix B) . When a 
branch is made to a label constant using 
the GOTO code in the TCA, a label temporary 
is created. The label temporary has the 



The optimizing compiler produces code that 
assumes that the registers retained across 
the execution of a labeled statement will 
be 2, 3, 12, and 13. These are the program 
base, the static base, the address of the 
TCA, and the address of the current DSA. 
All other register values may be different 
when control pases throjugh the labeled 
statement on different occasions. 

The enablement of conditions may differ 
in the GOTO statement and in the labeled 
statement. Within a block, the enablement 
status may be varied only for the duration 
of a single statement. The GOTO therefore 
resets the block enablement status before 
the branch is taken. If the labeled 
statement has a different enablement status 
from the block, it will be automatically 
reset in the labeled statement. 

As explained in chapter 7, "Error and 
Condition Handling," the enablement of 
conditions is recorded by enable cells. 
Two sets are used: the b lock enable cells 
retain the enablement situation at the 
start of the block, which can consequently 
be restored at any time; the curre nt enable 
cells hold the enablement situation that is 
current, which, as explained earlier, may 
differ from that at the start of the block. 

A GOTO within block normally takes the 
form of a simple branch instruction plus 
any alteration of the enablement bits that 
may be necessary to reset the enablement 
situation to that at the start of the 
block. Typical code would be: 



000F1A 47 FO 2 0C8 



B INPUT 
Branch to correct 
address in compiled 
code (label name is 
"INPUT") 



The optimizing compiler attempts to 
retain the same block base for all branches 
within a block. However, this is not always 
possible and, if the code for the block is 
longer than 4096 bytes, it may be necessary 
to set up a new base when a GOTO statement 
is executed. As all labels are stored with 
both their address and their base, this 
presents no problem. The address of the 
label and the value of its base form the 
value of the label constant. The value of 
the base is placed in register 2, and a 
branch is made to the label address. 
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When a GOTO to a label within the block 
is made, there is no need to reset 
registers 3, 12, or 13 as these are not 
altered within a block. 

Labeled statements within a block have 
an effect on optimization in that, apart 
from the bases and block addresses 
mentioned above, values cannot be retained 
in registers beyond a labeled statement. 



GOTO Out of Block 



GOTO statements that transfer control from 
a block have to overcome the problems 
described above, plus problems of block 
termination. 

For a GOTO out of block or to a label 
variable, compiled code makes a call to the 
GOTO code in the TCA, which is held at 
offset 128 (decimal) . The GOTO code 
receives, through registers 14 and 15, 
either the contents of the label variable 
or the equivalent information for a label 
constant, namely the address at which the 
label constant is held, and the address of 
the DSA of the block in which the label 
appears. 

The GOTO code first tests to see if a 
change of block is being made. If not, the 
enablement is reset as described below. If 
a change of block is being made, then, if 
FLOW or COUNT is in effect a call is made 
to IBMDEFL to update the flow or count 
tables. Next, the GOTO subroutine of 
IBMDPIR is called to determine if a valid 
GOTO is being undertaken. The GOTO 
subroutine ensures that the target block 
for the GOTO is still active and is not an 
invalid address. Provided that this is not 
an abnormal GOTO, registers 3 and 4 are 
restored from the target DSA, register 2 is 
loaded from the second word of the label 
constant, and register 13 is set to the 
address of the target DSA. The routine 
then branches to the appropriate point in 
code which is picked up from the address of 
the label constant, passed in register 14. 

The enablement situation at the start of 
the block has to be restored, and this is 
done by setting the current enable cells in 
the DSA to the value of the block enable 
cells. If the current enable cells 
indicate that CHECK is enabled, the module 
IBMDPGD is called. A search is made for a 
gualified CHECK ONCB, so that the enable 
cells may be set to the start-of-block 
situation in this ONCB. 

In a similar manner, it may be necessary 
to restore the NAB thalue to that at the 
start of the block* This will be necessary 



if the statement that invoked the block 
acquired a VDA. The start-of-block NAB 
value is retained in the DSA and is known 
as the end-of-prologue NAB. If a VDA has 
been acquired, the fact is flagged in the 
flag byte of the DSA, and the GOTO code 
places the end-of-prologue NAB value in the 
current NAB field. 

Such action is never required within a 
block, as VDAs are only acquired for the 
duration of one statement and are never 
used for GOTO statements. Typical code 
would be: 

GOTO label-constant (out of block) 



000226 18 F6 
000228 41 E0 3 088 
00022C 47 F0 C 080 



LR 15,6 

Place address of DSA 

in R15 

LA 14,136(0,3) 

Place address of 

label constant in R14 

B 128(0,12) 

Branch to GOTO code 

in TCA 



GOTO Label Variable 



GOTO label variable statements are treated 
in different ways depending on whether 
optimization has been specified. 

For NOOPTIMIZE, they are all treated as 
GOTO out of block; for OPTIMIZE (TIME) , a 
check is made to determine whether they 
could be out-of-block branches. The check 
is made by testing a label list, which is a 
list of the label constants to which the 
label variable may be assigned. If the 
programmer has supplied a label list, it is 
used. Otherwise, a list is generated 
containing all the label constants that are 
assigned to label variables. If a branch 
to any of the labels in the list could 
result in a GOTO out of block, all GOTO 
statements referring to the label variable 
are treated as GOTO out-of-block 
situations. Typical code would be: 



GOTO label-variable 



0000D0 98 EF D 0A8 



0000D4 47 F0 080 



LM 14,15,168(13) 
Load R14 and R15 with 
label variable 
B 128(0,12) 
Branch to GOTO code 
in TCA 



GOTO Only On-onits 



On-units containing only a GOTO statement 



Chapter 2: Compiler Output 27 



are not compiled as 
blocks. Instead the 
(ONCB) normally used 
unit, is specially f 
containing the on-un 
the offset within th 
word which contains 
variable or label te 
or temporary contain 
label constant to wh 
transferred and the 
label constant. 



separate program 
ON con trol block 
to address the on- 
lagged and, instead of 
it address, contains 
e associated DSA of a 
the address of a label 
mporary. This variable 
s the address of the 
ich control is to be 
DSA associated with the 



Before an on-unit is entered, the error 
handling module, IBMDERR, inspects the ONCB 
and, for a GOTO only on-unit, transfers 
control by loading registers 14 and 15 with 
the label variable or temporary and passing 
control to the GOTO code in the TCA. 



Interpretive GOTO Subroutine 



I If the test in the GOTO subroutine in 
IIBMDPIR indicates that an abnormal GOTO may 
| occur, control passes to the interpretive 
JGOTO subroutine. This routine is held as 
I another subroutine of the initialization 
| routine IBMDPIR, and is conseguently always 
| link-edited. 

All the situations that can lead to 
abnormal GOTOs are handled by library 
routines. When these routines are entered 
they flag the TCA and their own DSA to 
indicate that an abnormal GOTO may occur. 

The interpretive GOTO subroutine chains 
back through the DSA's and when it finds 
the flagged DSA passes control to the 
associated Module which does any necessary 
housekeeping. 

The special ca|ses in which the 
interpretive GOTO subroutine is called are: 

GOTO out of a SORT E35 or E15 routine. 

GOTO out of an EVENT I/O on-unit. 

GOTO out of an on-unit which results in 
the termination of a COBOL or 
FORTRAN routine. 

These situations are covered more fully in 
the relevant sections of this publication 
(See index) . 

The interpretive GOTO subroutine is 
described in DOS PL/I Resid ent Library 
Program Logic manual. 



Argument and Parameter Lists 



In PL/I usage, a parameter list is a list 
of the items a program expects to be 
passed; an argument list is a list of the 
items that are passed by the calling 
routine. 

Between PL/I routines, addresses are 
always passed rather than the arguments 
themselves. For strings, structures, 
arrays, and areas, the addresses of 
locators are passed rather than the 
addresses of the arguments themselves. The 
format of locators and the reasons for 
their use are given in chapter 4. 

When arguments are passed to routines 
whose entry points are declared with the 
ASSEMBLER, COBOL, or FORTRAN attribute, the 
address of the data itself must be passed. 
The method used is described in chapter 13, 
"Interlanguage Communication. " 

Arguments are passed in an argument list 
addressed by register 1. Normally the list 
is set up" in static storage. The addresses 
are loaded into consecutive registers and 
placed in the list by an STM instruction. 
If the procedure is reentrant or recursive, 
the list is moved into the temporary 
storage area of the DSA before the call is 
made. 

The addresses passed in the argument 
list are moved into the parameter storage 
area, which is held at the head of 
temporary storage and is addressed by 
register 4. (See figure 2.9.) Parameters 
are then accessed by picking up the 
addresses from this area. 

Dummy arguments, when they are reguired, 
are set up by the calling program. 
Conseguently, the called program can treat 
all arguments in the same manner. 



LIBRARY CALLS 



Library calls are a feature of every object 
program. All library calls that appear in 
the object-program listing are to modules 
in the resident library. Transient library 
routines are called by bootstrap routines 
which are held in the resident library. 

The number of library calls used depends 
on the source program and the level of 
optimization specified. For OPTIMIZE 
(TIME) , the minimum number of library calls 
will be made. If NOOPTIMIZE is specified, 
library calls will be made where this will 
speed compilation. The standard default is 
NOOPTIMIZE. 



28 



LA 1,40(0,4) 

LA 14,VO..U(11) 

LA 15,DED..VO.. 

U(11) 
STM 14,15,0(1) 

L 15,A..IBMBSLOA 



BALR 14,15 



Point R1 at argument 

list 

Load address of 

argument in register 

Load address of 

argument in register 

Store into argument 

list 

Pick up address of 

routine from static 

internal control 

section and place in 

R15 

Branch and link to 

routine 



Example 1. Call to library routine that 
has been link-edited and whose address 
is held in the static internal control 
section. The arguments passed are 
addressed by register 1. 



L 15,116(0,12) 
BALR 14,15 



Load address of 
routine held in TCA 
Branch and link to 
routine 



Example 2. Call to library routine 
whose address is held in the TCA 



Figure 2.10. 



Examples of library 
calling seguences 



Figure 2.11 shows examples of seguences 
used for calling library modules. The 
majority of library calls can easily be 
recognized by the appearance in the listing 
of the letters "IBM" followed by five 
letters specifying the module name and 
entry point. To call a module, its address 
is loaded into register 15, and a BALR 
instruction is carried out on registers 14 
and 15. 

The fifth letter of the entry point name 
is mnemonic of the type of module that is 
being called. Figure 2. 12 gives the 
meaning of the mnemonics. Full details of 
the library modules are given in the 
program product publications DOS PL/I 
Tra nsient Libra r y; , , Program Logic and DOS 
PL/I R esident Library : Program . Lpg ic. 

A further discussion of library module 
naming conventions is given chapter 3. 



an argument list must normally be set up. 
This is done in one of several ways, 
depending on the library module. The 
majority of library calls reguire the 
method shown in figure 2.10, example 1. 
This consists of loading the list into 
seguential registers starting at register 
14, and then using a store-multiple 
instruction to place the arguments into an 
area of static storage, whose address is 
then loaded into register 1. Argument 
lists are set up as far as possible during 
compilation and, where necessary, completed 
during execution. 



Addressing the Subroutine 



Library addresses are normally held in 
static storage and addressed as an offset 
from register 3. However, the addresses of 
certain library routines are held in the 
TCA or the TCA appendage and addressed from 
register 12. They are addressed either 
directly or indirectly as shown in example 
2 of figure 2.10. The names of these 
routines do not appear on the listing; 
however, they can be identified by their 
offset from the start of the TCA (see 
figure 2.12) . 



r ~ 

| IBMBA 


Array handling | 


| IBMBB 


String handling | 


| IBMBC 


Conversion | 


| IBMBE 


Error handling | 


| IBMBI 


Interlanguage communication | 


| IBMBJ 


Date/time/delay/wait | 


| IBMBK 


Dump/sort/checkpoint/restart \ 


| IBMBM 


Mathematical I 


| IBMBO 


Open/close I 


| IBMBR 


Record I/O I 


| IBMBS 


Stream I/O | 


| IBMBT 


Completion pseudovariable | 




routine | 



Settin g-Up Argument Lists 



Before a call is made to a library module. 



Figure 2.11. Mnenomic letters in 
library module entry-point names 
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DO-LOOPS 



END; 



Where possible, do-loops are carried out by 
means of a BXLE instruction, because this 



Note: For the code to be compiled in the 
manner shown below, J must not be accessed 
during the loop, nor after the loop until a 
new value has been assigned. 



Offset from 


Name of 


Use 


start of TCA 


module 




(Register 12) 


entry 
point 










Decimal j 


Hex 






72 


48 


IBHBPGRD 


Stack overflow 
routine to 
get VDA 


108 


6C 


IBMBPGRA 


Get non-LIFO 

dynamic 
storage 


112 


70 


IBMBPGRB 


Free non-LIFO 

dynamic 

storage 


116 


74 


IBMBPGRC 


Stack overflow 
routine for 
prologue 


120 


78 


IBMBERRB 


Error handler 

software 

interrupt 


264 


108 


IBMBJWTA 


WAIT module 


268 


10C 


IBMBTOCA 


Completion 
pseudo variable 
routine 


272 


110 


IBMBTOCB 


Event variable 

assignment 

routine 



Figure 2.12. Offsets where addresses 
of library modules are held in the TCA 



is more efficient than using a simple BCT 
instruction. BXLE do-loops can be used 
where the control variable cannot be 
altered except at the head of the loop, and 
where it is not subsequently accessed after 
the completion of the loop. BXLE do-loops 
cannot be used for the outer of a number of 
nested do-loops. For outer loops, other 
branch instructions are used. Code for two 
of typical nested do-loops is shown below. 
Note that the code will differ according to 
the context of the loop. 



Object progra m 
1 . Code for oute r do-loop 
LH 



5,596(0,3) Pick up 1 from 
constants pool 



STH 
CL.1 EQU 



5,1 
* 



Place 1 in I 



LH 


5,1 


AH 


5,596(0,3) 


STH 


5,1 


C 


5,598(0,3) 



BNH 



CL. 1 



Increment and 
store in I 
Compare I and 
constant 10 in 
static storage 



2. Co de for inner do-loo p 
LH 



CL.2 



LH 
LH 
EQU 



5,596(0,3) Place 1 in 

first operand 

10,596(0,3) Place 1 in 

second operand 

11,598 (0,3) Place 10 in 
comparand 

* 



BXLE 



5, 10, CL.2 



Increment, 
test, and 
branch if 
necessary. 



COMPILER-GENERATED SUBROUTINES 



Source program 

DO I = 1 to 10; 
DO J = 1 to 10; 



END; 



The compiler uses internal subroutines to 
carry out certain functions. These have 
the advantage over library modules, because 
they can be tailored for the most common 
case. When special cases arise, the 
library routines are called. Compiler- 
generated subroutines have the further 
advantage that they are internal to 
compiled code and consequently need not 
follow the standard operating system 
calling sequence. 
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Compiler-generated subroutines are used 
for the following purposes. 



IELCGIA 



IELCGIB 



IELCGOA 



IELCGOB 



IELCGOC 

IELCGMV 
IELCGCL 

IELCGCB 
IELCGON 
IELCGRV 
IELCGBB 
IELCGBO 



Stream I/O input - provides 

address of source of next 

edit-directed data or format 

item 

Stream (edit) I/O input - 

housekeeping after 

transmission of data item 

Stream I/O output - provides 

address of target of next 

edit-directed data or format 

item 

Stream I/O output - updates 

FCB, counts data item, and 

frees VDA if one was used 

Stream I/O - processes X 

format items 

Move long (registers 6,7,8,9) 

Compare long (registers 

1,6,7,8,9) 

Compare long bits 

Dynamic ONCB chaining 

Revert VDA chaining 

Test for * 1* bits 

Test for • 0* bits 



optimization phases are not called; no 
attempt is made to study the flow of the 
program, and the examination of compiled 
code for possible improvements is not 
undertaken on a global basis. More library 
calls will generally be made if NOOPTIMIZE 
is specified. 



EXAMPLES OF OPTIMIZED CODE 



A number of the more noticeable effects of 
optimization are shown below. These are 
code seguences which may prove difficult to 
understand without knowledge of the 
objectives of optimization. Where possible, 
the examples of code given are expansions 
of the examples shown in the language 
reference manual for this compiler. The 
examples do not attempt to cover all 
optimization carried out by the compiler. 



Elimination of Common Expressions 



Compiler-generated subroutines are held in 
separate control sections and are printed 
at the head of the object-program listing 
if they are used in a program. 



Optimization and Its Effects 



Optimization is the attempt to produce the 
most efficient possible object program. 
The DOS PL/I Optimizing Compiler adopts a 
threefold approach: 

1. It attempts to compile each statement 
in the most efficient manner. 



This is done by avoiding multiple 
calculations of the same expression, by 
holding the value either in temporary 
storage or in a register. In the examples 
shown below, the common expression is 
"B+C". In the first example, the value is 
held in a register. In the second, it is 
held in temporary storage, because the 
value to which it is first assigned is 
altered. In certain circumstances, the 
code could be compiled to move the value 
from the variable to which it was 
originally assigned to the second variable. 

Example 1 ; Value held i n register 



2. It modifies the resulting code for 
each block, in an attempt to make it 
more efficient (for example, by 
maintaining values in registers and by 
using common control blocks for 
similar items) . 

3. It examines the source program to 
discover whether statement flow can be 
reorganized to produce a more 
efficient program (for example, by 
moving code out of loops) . 

The effect of specifying the compiler 
option OPTIMIZE (TIME) is that the compiler 
loads and calls the optimization phases, 
and executes optimization code in other 
phases. The optimization phases are 
described in the publication DOS PL/I 
Optimiz ing Com pile r: Program Logic . 

When NOOPTIMIZE is specified, the 



Sou rce program 

2 A=B+C; 

3 IF X<Y THEN X=Y ; 
H D=B+C; 

Object program 



000062 


78 00 D 0A4 


LE 


0,B 


000066 


7A 00 D 0A8 


AE 


0,C 


00006A 


70 00 D 0A0 


STE 


0,A 


* STATEMENT NUMBER 3 






00006E 


78 60 D 0AC 


LE 


6,X 


000072 


79 60 D 0B0 


CE 


6,Y 


000076 


47 B0 2 020 


BNL 


CL.2 


00007A 


78 60 D 0B0 


LE 


6,Y 


00007E 


70 60 D 0AC 


STE 


6,X 



000082 



CL.2 EQD * 
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* STATEMENT NUMBER 



* CALCULATION OF COMMONED EXPRESSION 
FOLLOWS 
000082 70 00 D 0B4 STE r D 



Exam£le_2i Value held .in temporary st orag e 



Example 1; Do-lopp 



Source program 

2 
3 

4 



A=B+C; 

IF X<Y THEN A=6; 

D=B+C; 



Note: A may be altered before subsequent 
use of expression. 



Object pro g ra m 



* STATEMENT NUMBER 2 
000062 78 00 D 0A4 
000066 7A 00 D 0A8 
00006A 38 20 
00006C 70 20 D 0A0 

* STATEMENT NUMBER 3 



LE 0,B 

AE 0,C 

LER 2,0 

STE 2, A 



000070 


78 


60 


D 


0AC 


000074 


79 


60 


D 


0B0 


000078 


47 


B0 


2 


024 


00007C 


78 


20 


3 


010 


000080 


70 


20 


D 


0A0 


000084 








i 



CL.2 



LE 

CE 

BNL 

LE 

STE 

EQU 



6,X 

6,1 

CL.2 

2,20(0,3) 

2, A 

* 



* STATEMENT NUMBER 



* CALCULATION OF COMMONED EXPRESSION 
FOLLOWS 
00008A 70 00 D 0B4 STE 0,D 



Source^ 


prograi 


m 


3 
4 
5 
6 
7 




DO 1=1 TO N; 
J=3; 

A(I)=B(I) ; 

END; 
END; 



Object program 



* STATEMENT NUMBER 3 






00005E 


48 E0 D 0AA 


LH 


14, N 


000062 


48 60 3 010 


LH 


6,16(0,3) 


000066 


40 60 D 0A8 


STH 


6,1 


00006A 


19 6E 


CR 


6,14 


00006C 


47 20 2 036 


BH 


CL.3 



* INITIALIZATION CODE FOR OPTIMIZED LOOP 
FOLLOWS 

* CODE MOVED FROM STATEMENT NUMBER 4 
000070 48 80 3 012 LH 8,18(0,3) 
000074 40 80 D 0AC STH 8, J 

* CODE MOVED FROM STATEMENT NUMBER 5 
000078 48 90 3 014 LH 9,20(0,3) 
00007C 18 7E LR 7,14 
00007E 8B 70 002 SLA 7,2 

* CONTINUATION OF STATEMENT NUMBER 3 

LR 5,9 
LR 11,7 
LR 10,9 

CL.2 EQU * 

* STATEMENT NUMBER 4 



000082 


18 


59 


000084 


18 


B7 


000086 


18 


A9 


000088 







Movement of Expressions out of Loops 



When expressions cannot be altered inside a 
section of code that may be executed a 
number of times, the expression is moved 
out of the loop to- a position where it will 
be executed only once, regardless of the 
number of times that the loop is executed. 
The process is known as movement of 
invariant expressions. The most obvious 
example is in do-loops. However, the 
compiler analyzes the source program for 
other types of loop and also moves code 
from these. 

Example 1 shows code moved from a do- 
loop. Example 2 shows code moved from a 
loop that has been detected by the 
compiler. It should be noted that code 
moved out of loops frequently involves 
conversion and is not obvious in the source 
program. 



* STATEMENT NUMBER 5 
000088 78 25 D 0D4 
00008C 70 25 D 0AC 

* STATEMENT NUMBER 6 
000090 87 5A 2 02A 
000094 CL.3 



LE 
STE 



2,VO. .B(5) 
2,VO..A(5) 



BXLE 5, 10, CL.2 
EQU * 



Example 2 : Compile r-detected loop 
Source program 

2 L: IF X>Y THEN GOTO BED; 

/♦LOOP BEGINS*/ 

3 J=I-N; 

4 X=X+J; 

5 GO TO L; /*LOOP ENDS*/ 

6 BED: A=X; 



Object program 

* INITIALIZATION CODE FOR OPTIMIZED LOOP 
FOLLOWS 
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* CODE MOVED FROM STATEMENT NUMBER 3 
000066 48 EO D OAE LH 14,1 
00006A 4B EO D OBO SH 14, N 
00006E 50 EO 4 028 ST 14,40(0,4) 

* CONTINUATION OF STATEMENT NUMBER 1 

* STATEMENT NUMBER 2 



* STATEMENT LABEL L 
000072 78 00 D 0A0 
000076 79 00 D 0A4 
00007A 47 20 2 042 



LE 


0,X 


CE 


0,Y 


BH 


BED 



* STATEMENT NUMBER 



* CALCULATION OF COMMONED EXPRESSION 



FOLLOWS 






00007E 58 60 4 028 


L 


6,40(0,4) 


000082 40 60 D OAC 


STH 


6, J 



7 ELSE C=B*C; 

8 LABEL: X=X+1; 



Object program 

* STATEMENT NUMBER 5 
00008A 47 FO 2 028 B 

* STATEMENT NUMBER 8 

* STATEMENT LABEL LABEL 
00008E 78 60 D OAC LE 
000092 7A 60 3 018 AE 



000096 70 60 D OAC 
Compiler message reads: 



LABEL 



6,X 

6,24 

(0,3) 

STE 6,X 



"6,7 STATEMENT MAY NEVER BE EXECUTED. 
STATEMENT IGNORED. " 



* STATEMENT NUMBER 



* END OF COMMON 


CODE 






000086 


50 60 4 


030 


ST 


6,48(0,4) 


00008A 


48 60 3 


020 


LH 


6,32(0,3) 


00008E 


40 60 4 


030 


STH 


6,48(0,4) 


000092 


97 80 4 


032 


XI 


50(4) ,X»80« 


000096 


78 60 4 


030 


LE 


6,48 (0,4) 


00009A 


7B 60 3 


020 


SE 


6,32(0,3) 


00009E 


3A 60 




AER 


6,0 


0000A0 


70 60 D 


0A0 


STE 


6,X 



* STATEMENT NUMBER 5 
0000A4 47 FO 2 00C 

* STATEMENT NUMBER 6 

* STATEMENT LABEL BED 
0000A8 70 00 D 0A8 



STE 0,A 



Elimination of Unreachable Statements 



If the source program contains statements 
that can never be executed because they are 
unconditionally branched around, these 
statements will be ignored by the compiler. 

In the example below, the statements 
between 5 and 8 can never be reached. 
Consequently, no code is compiled for these 
statements, and a compiler diagnostic 
message is issued to indicate that this is 
the case. 



Examp le 
Source program 



5 GOTO LABEL; 

6 IF A<B THEN 



IF B<C THEN 



Simplification of Expressions 



Certain expressions are simplified for 
speedier execution. For example, 
multiplication is simplified to addition, 
as in the following example. 



Example: Multip lication into addition 

Source statement 
2 X=3*B 



IF A<X THEN 
B=B*C; 



Object program 

* STATEMENT NUMBER 2 

000062 78 20 D 0A4 LE 2,B 

000066 3A 22 AER 2,2 

000068 7A 20 D 0A4 AE 2,B 

00006C 70 20 D 0A0 STE 2,X 



Mod ification of DO-Loop Control 
Variables 



When the do-loop control variable is used 
for accessing array elements, it is 
frequently modified to simplify addressing 
of the array elements. 

If, as in the example below, the 
elements of the array are four bytes long, 
it simplifies addressing to increment the 
loop control variable by 4 rather than by 
1. When this is done, the increment 
becomes the distance between the start of 
successive array elements. Provided that 
the original value of the loop control 
variable is the same as that of the first 
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Soff£ce_grogram 








2 DCL C(10) FLOAT DECIMAL (6); 

3 DCL B(10) FLOAT DECIMAL (6); 

4 DO 1=1 TO 10; 

5 C(I)=B(I); 

6 END; 
Object program 






* STATEMENT NUMBER 4 
000066 48 60 3 010 
00006A 40 60 D 0A0 


LH 6,16(0,3) 
STH 6,1 


Pick 
Place 


up 1 from static 

s in I 


* INITIALIZATION CODE 


FOR OPTIMIZED LOOP 


FOLLOWS 




* CODE MOVED FROM STATEMENT NUMBER 5 
00006E 48 EO 3 012 LH 14,18(0,3) 
000072 48 90 3 014 LH 9,20(0,3) 


Load 
Load 


"4" into R14 from static 
"40" into R9 from static 


* CONTINUATION OF STATEMENT NUMBER 4 
000076 18 B9 LR 11,9 
000078 58 AO 3 012 L 10,18(0,3) 
00007C 18 5E LR 5,14 
00007E CL.2 EQU * 


Load 
Load 
Load 


"40" into R11 for BXLE 
"4" into R10 
"4" into R5 


* STATEMENT NUMBER 5 
00007E 78 45 D 0A4 
000082 70 45 D OCC 


LE 4,VO..B(5) 
STE 4,VO..C(5) 


Pick 
Place 


up VO..B+R5 
i in VO..C+R5 


* STATEMENT NUMBER 6 
000086 87 5A 2 018 


BXLE 5, 10, CL.2 


Increment R5 by 4, test for end of 
loop, and branch or continue 



Figure 2.13. Code showing modification of do-loop control variable 



Source 



Obje ct program 



IF (A=D) | (C=D) THEN 
X=Y+Z; 



* STATEMENT NUMBER 
000062 78 00 D 0A0 
79 00 



000066 
00006A 
00006E 
000072 
000076 
00007A 
00007A 
00007E 
000082 
000086 



D 0A4 
47 80 2 018 

78 40 D 0A8 

79 40 D 0A4 
47 70 2 024 

< 

78 60 D 0B0 
7A 60 D 0B4 
70 60 D 0AC 



CL.3 



CL.2 



LE 


0,A 


CE 


0,D 


BE 


CL.3 


LE 


4,C 


CE 


4,D 


BNE 


CL.2 


EQU 


* 


LE 


6,Y 


AE 


6,Z 


STE 


6,X 


EQU 


* 



Pick up A 
Compare A and D 
Branch if equal 
Pick up C 
Compare C and D 
Branch if not equal 



X=Y+Z 



Figure 2.14. Code showing branch around redundant expression 
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bound of the array, the loop control 
variable in turn becomes the offset of the 
element from the virtual origin of the 
array. 

If the loop control variable is altered, 
this means that the increment and final 
value must also be altered* Thus the loop 
in the example below, instead of being 
incremented from 1 to 10 by 1, is 
incremented from 4 to 40 by 4. Note that 
the value of the loop control variable is 
set at the start of the loop but is not 
incremented. If the value of the loop 
variable is reguired after the loop has 
been executed, this type of optimization 
cannot take place. 

In the example in figure 2.13, the 
control variable is held in register 5 
using a BXLE instruction. The array 
elements are addressed by using register 5 
as the offset from the virtual origins of 
arrays C and B. As register 5 starts the 
loop with the value of 4 and is incremented 
by 4 for each iteration of the loop, this 
gives the correct address. Both arrays 
begin 4 bytes from their virtual origins, 
and each array element is 4 bytes long. 



Rationalizat ion of Program Branches 



When the length of a program is greater 
than 4096 bytes and, conseguently, it 
cannot be addressed from one base register, 
an attempt is made to update the base at 
the most efficient point, so that there 
will be as few changes of program base as 
possible during execution. The aim is to 
avoid any program branches which move from 
the scope of one base register to the scope 
of another. 

The program base register is register 2, 
and this is updated when necessary. As 
register 2 is reguired for in-line record 
I/O and TRT instructions, the program base 
is saved and restored after such use. 



Use of Com mon Co nstant s and Control 
Blocks 



Branching Around Redundant Expre ssions 



If a series of tests are to be made and 
action taken if any of the tests proves 
positive, the compiler takes the reguisite 
action as soon as the first positive test 
is found. 

In the example in figure 2.14, a test is 
first made to see if A=D. If so, the value 
of Y+Z is assigned to X without a further 
test being made to see if C=D. Note that 
the last test is for ineguality, so that if 
the variables are egual, control will 
continue with the code that assigns the 
value to X. 



Constants and control information used more 
than once are generated only once in static 
storage. Thus for the statements X=768, 
1=768, the constant value 768 will be 
picked up from the same address in both 
cases. Similarly, compiler-generated 
control information, such as DEDs and 
descriptors (see chapter 4) , are generated 
only once if a number of variables reguire 
identical control information. 

The process of avoiding duplication is 
known as commoning . It should be noted 
that constants may not be commoned if they 
are not used in the same way. In the 
following example, constant •123* is stored 
in a different form for assignment, and 
exponentiation. 
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Source program 

2 
3 
4 
5 
Object 



X=123; /*C0MMONED ITEM*/ 

Y=123*Z; 

V=V**123; 

A=123; /*COMMONED ITEM*/ 



000066 


78 00 3 020 


LE 


0,32(0,3) 


00006A 


70 00 D 0A0 


STE 


0,X 


* STATEMENT NUMBER 3 






00006E 


78 20 D 0A8 


LE 


2,Z 


000072 


6C 20 3 018 


ME 


2,24(0,3) 


00007A 


70 20 D 0A4 


STE 


2,Y 


* STATEMENT NUMBER 4 






00007E 


41 90 D 0B4 


LA 


9,V 


000082 


50 90 3 024 


ST 


9,36(0,3) 


000086 


50 90 D 02C 


ST 


9,44(0,3) 


00008A 


96 80 3 02C 


01 


44(3) ,X«80« 


00008E 


41 10 3 024 


LA 


1,36(0,3) 


000092 


58 FO 3 00C 


L 


15,A..IBMBMXSA 


000096 


05 EF 


BALR 


14,15 


* STATEMENT NUMBER 5 






0000B8 


78 20 3 020 


LE 


2,32(0,3) 


0000BC 


70 20 D 0B0 


STE 


2, A 



/♦COMMONED ITEM*/ 



/♦COMMONED ITEM*/ 



Figure 2.15. Code showing use of common constant 
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Chapter 3: The PL/I Libraries 



This chapter explains the use of libraries 
by the DOS PL/I Optimizing Compiler. The 
topics covered are: when and why library 
routines are called, why there is both a 
transient and a resident library, naming 
conventions, and two implementation topics 
that cover all library modules: the use of 
library workspace and the use of weak 
external references. 

The DOS PL/I Optimizing Compiler is 
designed to be used in conjunction with the 
DOS PL/I Resident Library and the DOS PL/I 
Transient Library. These libraries consist 
of sets of standard subroutines that are 
used for the majority of interfaces with 
the system and for those jobs that can be 
most efficiently done by the use of 
interpretive subroutines. The main areas 
where library modules are used are: 
input/output, error handling, storage 
management, conversions, mathematical 
functions, and various string- and array- 
handling operations. 

Use of library routines simplifies 
compilation by enabling the compiler to set 
up an argument list and generate a call to 
a subroutine, rather than compile the 
complete code. However, library 
subroutines are less efficient than 
compiled code, since they must be 
generalized routines, whereas compiled code 
can be specially tailored to the particular 
program being executed. Furthermore, a 
library call involves the overhead of 
saving and restoring registers, and may 
reguire the setting-up of various 
additional control blocks to describe the 
data (see chapter 4) * For these reasons, 
programs that are optimized for time use as 
few library calls as possible. 

The majority of interfaces between 
compiled code and the operating system are 
implemented via library routines. This is 
done mainly for reasons of implementation 
convenience, as such interfaces are in this 
way localized and minimized. 



Resident and Transient Libraries 



The DOS PL/I subroutine library is divided 
into two separate program products: the 
DOS PL/I Resident Library (Program Number 
5736-LM4) and the DOS PL/I Transient 
Library (Program Number 5736-LM5) . 
Resident library modules are link-edited 
with the executable program phase. 



Transient library modules are loaded into 
dynamic storage when they are required. 
When they are no longer needed, the storage 
is freed and may be overwritten. Resident 
library routines have the advantage of 
speed; transient library routines have the 
advantage of saving space. By using both 
types of library, it is possible to produce 

more .efficient programs. 

*■■ 

Routines in the transient library are: 
input/output transmitters, open and close 
modules, error message modules, and PLIDDMP 
routines. All other library routines are 
held in the resident library, including a 
number of bootstrap routines that load and 
call transient routines. 

The DOS PL/I libraries reside in two 
direct-access libraries. The resident 
library is on the relocatable library and 
the transient library on the core-image 
library. 

The internal logic of individual library 
modules is described in the publications 
DOS PL/I Resident Library: Pro g ram Logic 
and DOS P L/I Transient Library: Program 
Logic . However, in such cases as I/O, 
error handling, and conversion, where 
compiled code and a hierarchy of library 
modules are used in implementing certain 
features of PL/I, the overall logic is 
described in this publication. Similarly, 
an overall explanation of storage 
management and interlanguage communication 
is given in this publication. 



Naming Conventions 



Most PL/I library modules have names of 
seven letters, the first three letters 
being IBM. This identifies the module as 
belonging to one of the PL/I libraries. 
The remaining letters indicate which 
particular library the module was written 
for, and the use of the module. 

Each resident library module has two 
names, the control name (which uniquely 
identifies the module) and the link-edit 
name (which is used to link edit the module 
to the appropriate data set. The link edit 
name is the same as the name of the first 
entry point). See figure 3.1. The use of 
two names allows the compiler to call the 
appropriate module regardless of the actual 
module available on the system. For 
example, there are two NAIT modules, one 
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CONTROL NAME 



IBM 


IS) 


xyz* 



Identify module as part of a 
PL/I library 



D=specially written for DOS Mnemonic of module's 
B=shared by other PL/I function 

libraries 
G=see text 



EXAMPLES 



IBMDPIR 
IBMBEOC 
IBMGJWT 
IBMDREF 



ENTRY POINT NAME 



Resident library modules 



IBMBxyz followed by 
A, B,C,etc.** 



Transient library modules 



Control name followed by 
A, B, C, etc. 



IBMBPIRA 
IBMDREFA 



LINK-EDIT NAME 
Primary entry point name 



IBMBPIRA 
IBMBEOCA 
IBMBJWTA 
IBMDREFA 



■ Conversion modules sometimes have only two mnemonic letters to identify the function, 
and use two mnemonic letters to identify entry points: 



IBMBCH 
IBMCHXD 



** Certain IBMDxyz resident modules called only by other IBMDxyz modules, and not by 
compiled code have entry point names IBM DxyzA etc. 



IBMDSTFA 



Figure 3.1. Library module names 
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for machine configurations that support the 
WAITM macro instruction, and one for those 
that do not. (The WAITM macro instruction 
allows waits on multiple events.) These 
modules have different control names. 
Machine configurations that support the 
WAITM instruction will normally have the 
module with the control name IBMDJWT in 
their resident library. Machine 
configurations that do not support the 
WAITM macro instruction will have the 
module with the control name IBMGJWT. Both 
modules have the link-edit name, IBMBJWTA. 
The compiler can therefore generate 
appropriate ESD references without knowing 
which module is available on the system. 
(Note; Dnderlinings are not part of the 
name.) Link-edit names, and all entry point 
names called from compiled code, have the 
fourth letter "B". 

Resident library module entry points 
that can be called from compiled code have 
names in which the fourth letter is "B", 
regardless of the control name. An 
additional letter or letters are used to 
make up the name to 8 letters. Normally 
the primary entry point is "A" (IBMBJWTA) 
the second entry point "B" etc. Transient 
library modules and certain resident 
library modules not called directly by 
compiled code have entry point names 
consisting of the control name plus an 
additional letter. 



FORMAT OF LIBRARY WORKSPACE 



Library workspace is designed so that 
either level can be treated by the 
housekeeping routines in the same way as a 
DSA. Chainback fields to the calling 
block's save areas are held in the head of 
library workspace and, where more than one 
level of library workspace is used, a 
chainback field is set up to the previous 
level. Figure 3.2 illustrates the method 
of chaining employed. 



ALLOCATION OF LIBRARY WORKSPACE 



Library workspace is originally allocated 
within the program management area by the 
initialization routine IBMDPII. However, 
whenever an interrupt occurs and an on-unit 
is to be entered, a further two levels are 
allocated. This allows library modules to 
be called within an on-unit, without 
overwriting library workspace which may 
have been in use at the time of interrupt. 

Attached to each allocation of library 
workspace, including the initial allocation 
in the program management area, is an ON 
communications area (ONCA) . This is a 
control block used in error handling to 
hold condition built-in function values. 
ONCAs are described fully in chapter 7. 



Library Workspace 



For certain library routines, DSA (dynamic 
storage areas) are not acguired in the same 
way as they are for source program 
subroutines. Instead of the storage being 
acquired from the LIFO stack, space is 
allocated, in the program management area, 
for two pre-formatted DSAs. These DSAs are 
known as levels of library workspace. 
Their format can be seen in figure 3.2. 
Library workspace (LWS) , provides a fast 
method for library routines to obtain DSAs. 
All the library routines have to do is to 
address the DSA and set the chainback 
field. There is no need to test to see if 
there is enough space for the DSA, and the 
NAB pointer does not have to be reset, 
because the next available byte is not 
changed. 

The PL/I libraries have been so designed 
that two levels of library workspace are 
the maximum required. This does not mean, 
however, that more than two modules are 
never called. Some library modules - for 
example, the error handler - use DSAs in 
the LIFO stack for working storage. 



Library Modules and Weak External 
References 



Because of the modular structure of the 
library, a group of modules is frequently 
used to carry out some particular task. 
Conversions, for example, are normally done 
by using a series of modules, and the same 
is true of many of the mathematical built- 
in functions. For this reason, many 
library modules contain a number of 
external references to modules which may 
not be needed in a particular program. An 
example of this is shown in figure 3.3. To 
prevent unnecessary modules being link- 
edited, "weak external references" (WXTRNs) 
are used. WXTRNs are a special type of 
external reference designed to cater for 
this situation. 

Those entry points that are called only 
optionally are coded as WXTRNs. This 
prevents the linkage editor from loading 
these modules unless a separate external 
reference is made to them by the compiler. 
Thus the executable program phase does not 
contain modules that it never uses. 
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Flags 



Offset to ONCA 



Chain back field (to last DSA) 



Standard save area 



Address of next library workspace 



Current NAB 



Workspace for library modules 



Flags 



Offset to ONCA 



Chain back field 



Standard save area 



Address of this level of LWS 

(used only when addressing the ONCA) 



Current NAB 



Workspace for library modules 



Current ONCA 



mm. 




1st level 



2nd level 



Figure 3.2. Library workspace 



HO 



r 



IBMBSFI 



F -format input 
conversion director. 
Contains WXTRNs for: 
IBMBCCSA, IBMBCTHD, 
etc. 



IBMBCCS 

Special string conversion 
module. Contains WXTRNs for: 
IBMBCCAA, IBMBCACA, etc. 



< 



V 



IBMBCTH 



E- or F-format-to-arithmetic 
conversion module. Contains 
WXTRNs for: 
IBMBCEZX, IBMBCHZD,etc. 



Figure 3.3. Example of use of WXTRNs 



Figure 3.3 shows part of a hierarchy of 
modules with alternative paths through 
them. When such a hierarchy exists, the 
actual path to be taken through the modules 
will be known to the compiler, and external 
references will be made to all the reguired 
modules whose names are coded as WXTRNs. 
The effect of this is that the linkage 
editor loads only these modules. 
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PL/I allows the programmer the choice of a 
larqe number of data attributes. Normally 
there is no need for explicit attribute 
information to be retained until execution, 
because the methods used to handle the data 
can be resolved during compilation. 
However, there are certain situations where 
this cannot be done. For example, the 
attributes of the data may not be fully 
known at compile time, because of 
adjustable bounds or lengths, or the data 
may be passed to another PL/I program or 
PL/I library subroutine. When these 
situations arise, it is necessary to retain 
some or all of the data attributes in an 
explicit form throughout execution. 

The names of variables fall into a 
similar category. Normally, they need not 
be explicitly known during execution. 
However, for data-directed input/output and 
the CHECK condition, the names of the 
variables need to be known so that they can 
be associated with the correct values. 

When such information must be retained 
until execution, special control blocks are 
set up for the purpose. These control 
blocks are described in this chapter. The 
following control blocks are used. 

Descriptors; These hold the extent of the 
data item (i.e., string lengths, array 
bounds, and area sizes). 

Locators; These hold the address of a data 
item and are either concatenated with the 
descriptor, or hold the address of the 
descriptor. 

Desc riptor Descriptors : These hold the 
logical structure levels, dimensions, and 
lengths, of all elements within a 
structure. 

Data E lement Descriptors (DED s) : T he se 
hold the attributes of a variable required 
for data manipulation, except for extents, 
which are held in descriptors. 

Symbol Table s; These hold the names of the 
variables and associate them with the 
appropriate storage locations during 
execution. 

Symbol Table Vector ; This associates 
symbol tables with the block in which they 
are known. 

An example of the way in which data is 
related to its locators, descriptors, and 
DEDs is given in figure 4.1. 



Notes o n Termino logy 



The following terms are used in this 
chapter. 



Virtual origin (VO) 



Actual origin (AO) 



Relative virtual 
origin (RVO) 

Structure element 



Base element 



The address where the 
element of an array 
whose subscripts are 
all zero is held or, if 
such an element does 
not appear in the 
array, where it would 
be held. 

The byte address of the 
first item in the array 
or structure. 

Byte actual origin 
minus virtual origin. 

A minor or major 
structure that contains 
a number of base 
elements. 

A data element or array 
within a structure. 



DESCRIPTORS AND LOCATORS 



Descriptors are generated when adjustable 
extents are involved, or when an item is to 
be passed as an argument and the associated 
parameter is the type that can be declared 
with an asterisk among its attributes. For 
example, DCL X CHAR (N) ; or DCL X CHAR (*) ; 
would both result in the generation of a 
descriptor. In the first case, code for the 
SDBSTR built-in function would have to be 
interpretive if STRINGSIZE were enabled. 
The appropriate library module would be 
called, and it would make use of the 
descriptor to discover the length of the 
string. This length would have been placed 
in the descriptor by the prologue code of 
the block in which the string was declared. 
In the second case, where the length of the 
string is signified with an asterisk, the 
program that is passed the string will 
expect to receive the length of the string 
in a descriptor. 

Data items that can be declared with an 
adjustable value or an asterisk are: 
string lengths, array bounds, and area 
sizes. Descriptors are, therefore, needed 
for strings, arrays, and areas. They are 
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Storage 



PL/1 Statement 
DCL TABLE (10) 
FLOAT DECIMAL (6); 



TABLE (0) 



TABLE (I! 



TABLE (9) 



TABLE (10) 



mpus 



Short floating-point decimal 6 



Address of TABLE 



Address of descriptor 



■m 



* RVO=4 



Multiplier=4 



Upperbound-10 



Lowerbound=1 



Virtual origin 



Array TABLE (10) 



DED 



Aggregate locator 



Array descriptor 



*RVO (Relative virtual origin) is the offset of the actual 
origin of the array from the virtual origin (the position that 
element TABLE (0) would hold if it existed) 



Figure 4.1. 
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Example of descriptors, locators and DEDs for an array 



Name of control block 



Conditions under which it is 
generated 



Location 
(control section) 



Data element descriptor (DED) 



Array descriptor 



Aggregate locator 



Area locator/descriptor 



String locator/descriptor 



Structure descriptor 



Aggregate descriptor 
descriptor 

Symbol table 



Symbol table vector 



When conversion or stream I/O library 
modules are called. 

When an array has adjustable bounds 
or may be passed to a library 
subroutine or other PL/I routine. 

When structure or array descriptor is 
generated. 

When an area is declared with an 
adjustable size or may be passed as 
an argument. 

When a string is declared with an 
adjustable length or is passed as an 
argument. 

When a structure is declared with 
adjustable elements or is passed as 
an argument. 

When a structure contains elements 
declared with adjustable bounds. 

When an item may appear in 
data-directed I/O or in a 
CHECK list 



When GET DATA or PUT DATA is used 
without a data list, or when SIGNAL 
CHECK is used without a data list. 



Static internal 
Static internal 

Static internal 
Static internal 

Static internal 

Static internal 

Static internal 



Static internal 
for internal 
items. Separate 
CSECT for 
external items. 

Static internal 



Figure 4.2. Descriptors, locators, and symbol tables: when generated, where held 



also needed for structures, because 
structures can contain strings, arrays or 
areas. 

In order to connect the data with its 
descriptor, a further control block is 
generated. This is the locator. The 
locator addresses both the descriptor and 
the variable. For strings and areas, the 
locator is concatenated with the descriptor 
and contains only the address of the 
variable. For structures and arrays, the 
locator is a separate control block and 
holds the address of both the variable and 
the descriptor. Called routines are 
normally passed the addresses of locators, 
rather than the addresses of arguments when 
arguments reguiring descriptors are passed. 

When the descriptor and locator are not 
concatenated, it is possible to use the 
same descriptor for a number of different 
data items, provided that these items have 
the same attributes. This process is known 
as "commoning" and is used to conserve 



space. Where possible, the compiler 
commons structure and array descriptors and 
aggregate descriptor descriptors. 

Descriptors and locators are always held 
in the static internal control section, 
regardless of the attributes of the data 
that they describe. 

The following types of descriptor ahd 
locator are generated. Figure 4.2 
summarizes the conditions under which they 
are generated and gives their storage 
locations. In the main, they are set up 
during compilation and completed during 
execution, if necessary. 



S t ring Locator /Des c riptor 



The string locator/descriptor holds the 
byte address of the string, information on 
whether or not it is a varying string, and 
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the maximum length of the string. For a 
bit string, the bit offset from the byte 
address is held. (See figure 4.3.) 



Area Locator/Descriptor 



The area locator/descriptor holds the 
address of the start of the area and the 
length of the area. (See figure 4.4.) 



ftqffEeqat e L ocator 



The aggregate locator holds the address of 
the start of the array or structure and the 
address of the array descriptor or 
structure descriptor. (See figure 4.5.) 



Array Descriptor 



The array descriptor holds: 



1. 



2. 
3. 



The relative virtual origin (RVO) of 
the array. This is the offset of the 
start of the first element in an array 
(actual origin) from the virtual 
origin. The virtual origin (VO) is the 
point at which element (0) would be 
held in a one-dimensional array, 
element (0,0) would be held in a two- 
dimensional array, etc. In a one- 
dimensional array, the address of any 
particular element can be discovered 
by multiplying together the subscript 
and the multiplier (see below) and 
adding the result to the virtual 
origin of the array. An extension of 
this method is used for multi- 
dimensional arrays, the formula being: 



Address of element (S^Sa,, 
= V0+ (M *S ) 



S n ) 



where S is the subscript number, and 
H the multiplier, of the ith 
dimension, and VO is the virtual 
origin. 

The high and low bounds for the 
subscripts in each dimension. 

The multiplier for each dimension. 
The multiplier is the distance between 
the start of one element and the start 
of the next element in the same 



dimension. For example in the array 
declared A (2, 2), the multiplier for 
the first dimension is the distance 
between the start of element A (1,1) 
and the start of element A (1,2). 

When the array is an array of strings or 
areas the string or area descriptor is 
concatenated with the end of the array 
descriptor to provide the necessary 
additional information. Array descriptors 
are commoned where possible. That is, one 
descriptor is used for a number of similar 
arrays. (See figure 4.6.) 



Str u cture Descrip tor 



This consists of a series of fullwords, 
giving the byte offset of the start of each 
base element from the start of the 
structure. If a base element has a 
descriptor, the descriptor is included in 
the structure descriptor, following the 
appropriate fullword offset. Where a bit 
offset is involved, this will be held in 
the descriptor for the bit string, or in 
the relative virtual origin if the item is 
a bit string array. 

A structure must be mapped during 
execution if any of the elements in the 
structure have adjustable bounds or 
extents, or if the REFER option is used. 
Where possible, structure descriptors are 
commoned. That is, one descriptor is used 
for a number of similar structures. If a 
structure or an array of structures 
contains elements with adjustable extents, 
the structure descriptor is not set up 
during compilation. Instead, it is set up 
during execution from information held in 
the aggregate descriptor descriptor. (See 
below for information on arrays of 
structures and structures of arrays.) 



Aggreg ate Descriptor Descriptor 



When a structure cannot be mapped during 
compilation, more information than is held 
in the structure descriptor is needed for 
it to be mapped during execution. This 
information is held in a control block 
known, as an aggregate descriptor 
descriptor. 

The information held in an aggregate 
descriptor descriptor is the dimensionality 
and logical level of all the structure 
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1 



Byte address of string 



Length 



7" 



Unused 



Bit offset 



^ 



For varying strings, the maximum 0=fixed length For bit strings only 

length is held 1=varying length 



Figure 4,3. String locator/descriptor (SLD) 



Address of first byte of area 



Allocated length of area (in bytes) 



Figure 4.4. Area locator/descriptor (ALD) 



1 



Byte address of first byte of aggregate 



Address of array or structure descriptor 



Figure 4.5. Aggregate locator (AL) 



RVO (Relative virtual origin) 


M 1 (multiplier) 


U 1 (upperbound) 


L 1 (lowerbound) 


l ' 
i I 




N 


In 


u n 


Ln 



Notes: 1. For unaligned bit strings, RVO and multiplier are bit values. 

2. For strings and areas, the area or string descriptor is concatenated 
to the end of the array descriptor. 

Figure 4.6. Array descriptor (AD) 



Multiplier and bounds 
for 1st dimension 



Multiplier and bounds 
for nth dimension 
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1 



Structure 



Offset (fullwords) 



. Offset of entry for containing structure from 
start of ADD (all ones for a major structure) 



0=structure 
1=base element 



Level 



\ 



Jr 



O=not bit string 
1=bit string 



Dimension 



1=last element 
0=not last element 



"Narea 
O=not area 



Alignment 



7 



Length (bytes) 



Base element 



All zero for areas and strings 



Obit 
7=byte 

15=halfword 
31=fullword 
63=doubleword 



There is a fullword entry in the ADD for each structure (major and minor) and each base element. 



Figure 4.7. Aggregate descriptor descriptor (ADD) 



elements, and the dimensionality, logical 
level, and alignment requirements, of all 
base elements, plus the length of those 
base elements that do not have their length 
held in descriptors. (Strings and areas, 
and arrays of strings and areas, have their 
lengths in descriptors.) The length held 
for an array is the length of an array 
element. The total length of the array can 
be calculated by using the information in 
the array descriptor. 

The aggregate descriptor descriptor is 
set up in static internal storage and is 
set up completely during compilation. The 
format is shown in figure 4.7. An example 
showing the method used to map a structure 
that contains an element with an adjustable 
extent is shown in figure 4.8. 



Where possible, aggregate descriptor 
descriptors are commoned. 



Arrays of S t ructures and Structures of 
Arrays 



Where necessary, an aggregate locator, a 
structure descriptor, and an aggregate 
descriptor descriptor are generated for 
both arrays of structures and structures of 
arrays. 

The structure descriptor for both an 
array of structures and a structure of 
arrays has the same format. The difference 
is in the values in the fields of the array 
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DURING COMPILATION 

-f Space for structure descriptor allocated in static 
storage. 

2 Aggregate descriptor descriptor allocated, and 
fields filled in from structure declaration. 

3 Aggregate locator allocated, and address of 
structure descriptor place in second word. 
Code is generated within the prologue of the 
block in which the structure is declared to call 
structure mapping routine, IBMBAMM, to 
acquire a VDA, and to complete the aggregate 
locator. 



DURING EXECUTION 

Prologue code daces value of N(1 byte) in 
the string descriptor for in structure 
descriptor. 

IBMBAMM is called to map the structure, 
using the information in the ADD and the 
SO (which contains the length of element 
D). D is aligned with E, then B is aligned 
with DE. (The rules for structure mapping 
are given in the language reference manual 
for this compiler.) The results of the 
mapping are placed in the structure 
descriptor. 

IBMBAMM returns the length of the 
structure to compiled code, which acquires 
a VDA for the structure and places the 
address of the structure in the aggregate 
locator. 



THE RESULT 

Every member of the structure can be addressed by 
means of the address in the aggregate locator and 
the offsets within the structure descriptor. When bit 
offsets are involved, they are contained within the 
appropriate descriptor in the structure descriptor. 



DURING COMPILATION 

SD 1 



I ► 


Space for offset of B 


Space for offset of D 


Space for descriptor of D 


Space for offset of E 




ADD 2 






01 


All ones 


Level 1 


00 


Zero 


10 


X'3V 


X'4' 


Level 2 


00 


Zero 


00 


Zero 


Level 2 


00 


Zero 


10 


X'7' 


Zero 


Level 3 


00 


Zero 


11 


X'31' 


X'4' 


Level 3 


00 


Zero 




AL 3 






Space for address of structure 


Address of structure descriptor 





DURING EXECUTION 

SD 5 



Zero 



1 byte 



X'8* 



ADD is unchanged during execution. 



For meaning of entries, see Figure 4—7. 



Declaration 
DCL 1 A, 

2 B FLOAT, 
2 C, 
3 D CHAR(N), 
3 E FLOAT; 





Address of structure 




Address of structure descriptor 




VDA for structure 6 






B 






D 




E 



Figure 4.8. Example of handling structure containing adjustable extent 
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Array of structures 



Structure of Arrays 



DCL 1 AR(10), 
2 B, 
2 C; 



DCL 1 



ST, 

2 B(10), 

2 C(10); 



Structure descriptor for AR 



Structure descriptor for ST 





Offset = 


AR.B 


RVO = 4 


Multiplier = 8 




Upperbound = 10 


Lowerbound = 1 




Offset = 4 




RVO = 4 


AR.C 


Multiplier = 8 




Upperbound = 10 


Lowerbound = 1 



ST.B 



ST.C 



Offset = 



RVO = 4 



Multiplier = 4 



Upperbound = 10 



Offset = 40 



RVO = 4 



Multiplier = 4 



Upperbound = 10 



Lowerbound = 1 



Lowerbound = 1 



Figure 4.9. Structure descriptors for arrays of structures and structures of arrays 



descriptors within the structure 
descriptor. Take for example the array of 
structures AR and the structure of arrays 
ST, declared below. 



Array of Structures Structure of Arrays 



DCL 



1 AR(10), 
2 B, 
2 C; 



DCL 



1 ST, 

2 B(10) , 
2 C(10) ; 



The structure descriptor for both AR and 
ST would contain an offset field for both B 
and C and an array descriptor for both B 
and C. (See figure 4.9.) However, the 
values in the descriptors would differ, 
because the array of structures AR would 
consist of elements held in the order 
B,C,B,C, etc., and the elements in the 
structure of arrays ST would be held in the 
order 
B,B,B,B,B,B,B,B,B,B,C,C,C,C,C,C,C,C,C,C. 



DATA ELEMENT DESCRIPTORS 



When data is passed to the PL/I library 
routines, a complete description of the 
data is frequently required, and something 
more than a descriptor is therefore needed. 
Conversion routines, for example, need to 
know the complete attributes of the data. 
To hold such information, data element 
descriptors (DEDs) are generated. (Control 
blocks known as DEDs are also used by the 
compiler. These are cpmpil e-time D EDs and 
have a different format from those that are 
used during execution. Compile-time DEDs 
never appear in the executable program.) 
For stream I/O, DEDs are generated to 
describe the format of the input or output. 
These DEDs are known as format element 
descriptors (FEDs) . 

DEDs are produced for all types of 
variable or temporary that are passed to 
the library for conversion or stream 
input/output. The length and format of the 
DED is dictated by the data type of the 
item. DEDs are shown in detail in appendix 
B. 
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DEDs are always held in static internal 
storage. They are used only to pass 
information to library routines. 

There are five types of DEDs: 
arithmetic DEDs, arithmetic pictured DEDs, 
string DEDs, pictured string DEDs, and 
FEDs. 

Arithmetic DEDs; are 4 bytes long. 

Arithmetic^pictured DEDs: (always decimal) 
are 8 bytes plus picture specification, 
which consists of at least one byte for 
every character in the pictured string. 
Maximum length for pictured arithmetic DEDs 
is 264 bytes. 

String DEDs; are 4 bytes long. 

Pictured string. .DEDs: (always character 
string) are six bytes plus the picture 
specification, which consists of one byte 
for every character in the picture string. 
The maximum length for pictured character 
DEDs is 261 bytes. 



FEDs (input/output DEDs) : 
classes 



fall into five 



blocks known as symbol tables or, 
sometimes, symtabs. Symbol tables hold the 
name of the variable, its address, and the 
address of its DED plus certain other 
information (see appendix B) . 

PUT DATA and GET DATA statements without 
a data list, and SIGNAL CHECK statements 
when there is no check list, imply that the 
names of all variables known at that point 
in the program must be available. This 
information is held in a further control 
block known as the symbol table vector . 
The symbol table vector holds the addresses 
of symbol tables arranged in order of 
program blocks, commencing with the main 
procedure block. The symbol table vector 
consists of a series of fullword fields. 
These fields contain either the address of 
a symbol table, a fullword of zeros, or a 
further address within the symbol table 
vector. The end of entries for symbol 
tables, for variables declared in each 
block, is followed by a fullword of zeros, 
which in turn is followed by the address in 
the symbol table vector where entries for 
the encompassing block begin. If there is 
no encompassing block, another word of 
zeros is used. 



3. 



A,B, and control format FEDs have four 
bytes. 

E and F format FEDs are six bytes 
long. 

Pictured arithmetic FEDs consist of 
four bytes followed by the pictured 
arithmetic DED. 



4. Pictured character string FEDs consist 
of four bytes followed by the pictured 
character string DED. 

5. C format FEDs are four bytes plus the 
two constituent FEDs that make up the 
complex item. They are used for 
complex data. 

The first two bytes of any DED are the 
look-up byte and the flag byte. Taken 
together, they define the data type and 
permit a receiving routine to determine if 
it needs to look further into the DED for 
more information. The general format of 
DEDs is shown in figure 4.10. Full details 
are given in appendix B. 



SYMBOL TABLES AND SYMBOL TABLE VECTORS 



Data-directed I/O statements, and the CHECK 
condition, reguire the names of variables 
to be available throughout execution. 
Normally, such names are not used after 
compilation. When reguired during 
execution, these names are held in control 



Figure 4.11 shows the relationship 
between variables, symbol tables, and the 
symbol table vector. 

Data-directed I/O modules, and the CHECK 
module, use symbol tables and symbol table 
vectors in the following ways. 

POT DATA (A.B. C) . GET DA TA (A. B.O. SIGN AL 

CHECK (A A B,C) : In all these cases, the 

addresses of the symbol tables for A, B, 
and C are passed to the appropriate library 
module. 

GET DATA, PUT DATA, SIGNA L CHECK: When no 
data or check list is included in the 
statement, the library is passed the 
address of the start of the associated 
block entries for the symbol table vector. 
By following the symbol table vector, it is 
possible to access the names of all the 
variables known in the block. 

The contents of symbol tables vary 
according to the storage class of the 
variable. The method used for holding the 
address, and other information, is given in 
appendix B. For internal variables, symbol 
tables are held in static internal storage. 
For external variables, symbol tables are 
held as separate control sections in static 
external storage. The name of each control 
section is the name of the associated 
variable followed by an *. Thus the 
control section for the external variable B 
would be B*. Such a control section would 
also contain the DED of the variable (or 
DEDs if the variable was a structure) . 
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String DED 



Look-up byte 


Flag byte 


Not used 



Arithmetic DED 



Look-up byte 


Flag byte 


Precision 


Scale 



Pictured string DED 



Look-up byte 


Flag byte 


Length of string 


Length of string without/insertion characters 


Translation of picture 


specification into internal format (one byte per character) 


^" 



Pictured arithmetic DED 



Look-up byte 


Flag byte 


Precision 


Scale 


Length of picture 


Length of data 


Mantissa byte 


Exponent byte 


Translation of picture specification into internal format (at least one byte per character) 


^ 



For details of look-up byte and flag byte conventions, see appendix B. 



Figure 4.10. Format of DEDs 
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PROGRAM BLOCK STRUCTURE 

Main procedure 



DCL A, B, C; 



Subroutine 1 
DCL X, Y, A; 



Subroutine 2 
DCL X, Y; 



Vector for 
main procedure 



Vector for 
subroutine 1 



Vector for 
subroutine 2 



fe 


Symbol table vector 


fe 


Symbol tables for: 


# 


A 


A in main procedure 




B 


B in main procedure 




C 


C in main procedure 


w 


00000 




00000 




X 


X in subroutine 1 


w 


Y 


Y in subroutine 1 


w 


A 


A in subroutine 1 


w 


00000 




-Pointer 




X 


X in subroutine 2 


w 


Y 


Y in subroutine 2 


w 


00000 




- Pointer 





The symbol table vector is built up on a block by block basis, the last entry for each block being a word of 
zeros followed by a pointer to the first entry for the encompassing block. This mechanism allows for 
multiple declarations of names. 



Figure 4.11. Symbol tables and symbol table vectors 
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Chapter 5: Object Program Initialization 



Before the output from the compiler can be 
executed as an executable program phase, it 
must be link-edited, and the PL/I 
environment must be set up. This chapter 
briefly describes the effects of link- 
editing, the manner in which the program is 
entered, and the initialization process 
that sets up the PL/I environment. 



Link-Editing 



Only one of these is resolved. 

The PLIMAIN control section is not 
generated by the compiler if the PL/I 
source program does not contain the MAIN 
option. Instead, a control section named 
PLIMAIN is included in the initialization 
module IBMDPIR. This control section 
contains the address of code that calls the 
module IBMDPEP, which puts out a message 
saying there is no main procedure and then 
terminates the program. 



The logic and effects of the linkage editor 
program are described in the publication 

IBM Sy stem/ 360 DOS: Introduction to Syst em 

Control Programs. This chapter describes 
the effects of link-editing on the PL/I 
program. The linkage editor combines the 
various control sections generated by the 
compiler and resolves addresses within 
these control sections. The linkage editor 
also incorporates into the executable 
program phase all library modules that are 
called from compiled code, and a number of 
other library modules that are reguired 
either because they in turn are called by 
the library modules called by compiled 
code, or because they are needed for 
program management. The most important of 
the modules used in program management are 
the error-handling module, IBMDERR, and the 
storage management module, IBMDPGB. An 
external reference to both of these modules 
is contained in the PL/I initialization 
routine, IBMDPIR. An external reference to 
IBMDPIR is included in the control section 
PLISTART which is generated by every 
compilation and nominated as its entry 
point. PLISTART contains an external 
reference to the control section PLIMAIN 
(which holds the address of the start of 
the main procedure) . 

One of the features of the linkage 
editor is that it does not accept more than 
one control section with the same name; the 
second use of the name is ignored. As a 
result of this, only one PLISTART and one 
PLIMAIN is generated for each executable 
program phase. This allows two or more 
PL/I main procedures to be link-edited 
together. The procedure that receives 
control will be the first that is passed to 
the linkage editor, because it will be the 
PLISTART and PLIMAIN of this procedure that 
are included in the executable program 
phase. This feature is also used to handle 
data declared EXTERNAL. Control sections 
for each such data item are generated by 
all programs in which the data is declared. 



Program Initialization 



Code is compiled by the PL/I Optimizing 
Compiler on the assumption that various 
control blocks will be set up and that 
certain registers will point to them when 
the program is entered. This arrangement 
of control blocks and registers is known as 
the PL/I environment. 

The most important factors affecting the 
PL/I environment are the following: 

1. A dynamic storage area (DSA) should 
exist before compiled code is entered. 
This will give the address of the area 
available for the first compiled code 
DSA and will act as a save area for 
the calling routine* s registers. 

2. A task communications area (TCA) 
should exist. The TCA acts as a 
central communications area for the 
program, holding addresses of various 
storage- and error-handling routines, 
and control blocks. The TCA also 
contains a number of flags and other 
fields. 

3. Program checks should- be passed to the 
PL/I error-handling module IBMDERR. 

4. Pre-f ormatted DSAs should exist for 
certain library routines. These Pre- 
formatted DSAs are known as library 
workspace (LWS) . 

5. A space should be available for any 
condition built-in function values 

(ONCHAR, ONSOURCE, etc.) should a 
PL/I interrupt occur. This space is 
known as an ON communications area 
(ONCA) . As the condition built-in 
functions have default values, an area 
to hold the default values is 
reguired. This is known as the dummy 
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PLISTART 



Receives control from 
system 

Passes control to 
initialization/ 
termination routine, 
IBMDPIR. 



Initialization routines 



Set up TCA, initialize storage and 
issue STXIT to initialize PL/I error- 
handling scheme. Pass control to 
the address in PLIMAIN. 



Prologue code 



Acquires DSA for main 
procedure, initializes 
control blocks, etc. 

Stores registers of 
initialization/ 
termination routine, 
IBMDPIR. 



Functional code 



Carries out function required 
in source program. This 
usually involves calls to 
library subroutines. 



Epilogue code 



Restores the registers of 
the initialization/ 
termination routine. 



Termination routine 



Closes any files still open and 
returns control to system with EOJ 
macro instruction, or returns 
control to caller. 



Figure 5.1. Flow of control during execution 



ONCA. 

6. Register 12 should point at the TCA, 
and register 13 should point to the 
DSA. 

The resident program initialization 
routine IBMDPIR, and the transient routine 
IBMDPII, which it calls, set up the various 
control blocks involved immediately 
following the executable program phase in 
an area known as the program management 
area. The contents of the program 
management area are described later in this 
chapter. 

Two similar initialization procedures 
are available for initializing the PL/I 
environment when a PL/I procedure is called 
from assembler language. These modules are 
IBMDPJR which is resident and carries out 
the same functions as IBMDPIR, and IBMDPJI 
which is transient and carries out the same 
functions as IBMDPII. The use of these 
modules prevents the normal PL/I program 
having an overhead of redundant code.. 

The advantage of having program 



initialization routines is that it obviates 
the need for special code in the prologue 
of main procedures and allows two 
procedures with the MAIN option to be used 
in one program. As shown in figure 5.1, the 
initialization routine IBMDPIR is re- 
entered after the execution of compiled 
code. Again, this is done automatically by 
standard epilogue code. This is because 
the registers of IBMDPIR have been stored 
by the prologue code and are restored by 
the epilogue code. The functions of 
IBMDPIR and IBMDPII are explained below. 



INITIALIZATION AND TERMINATION ROUTINES 



When called from the control program, 
IBMDPIR established the initial storage 
area (ISA) in that part of the partition 
that is not taken up by the executable 
program phase. It then calls the transient 
routine IBMDPII which sets up the program 
management area and issues a STXIT macro 
instruction so that program checks will be 
passed to the error handler. Control is 
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R12- 



NAB. 



PROGRAM MANAGEMENT AREA 



TCA 

Task communications area. 
See text and appendix B 



TCA Appendage 

See text and appendix B 



Dummy ONCA (ON communications area) 
Holds default values for condition built- 
in functions 



TRT Table 

Translate-and-test table for IBMDERR, used 
in error handling to test for relevant 
on-cells 



Diagnostic File Block 

Contains information relating to the use 
of SYSPRINT for the transmission of 
diagnostic messages 



Save area for IBMDPGR 

Used by storage management routines when 
new segment of storage is required 



Dummy DSA (Dynamic storage area) 
Contains DSA for initialization routine, 
backchain to calling routine's save area 
(if any), pointer to start of major free 
area (NAB), etc. 



LWS (Library workspace) 

Two preformatted DSAs for use by certain 
library routines 



ONCA 

Space in which condition built-in function 
values are placed after an interrupt. 
Backchain points to dummy ONCA 



Caller's STXIT options 

Save area for caller's STXIT program check 
options 




then returned to IBMDPIR which passes 
control to the procedure whose address is 
held in the control section PLIMAIN. 
Before passing control, register 13 is 
pointed to the dummy DSA and register 12 to 
the TCA. The dummy DSA will be used by 
compiled code to sotre IBMDPIR's registers. 

On return frcm compiled code, IBMDPIR 
raises the FINISH condition by calling the 
error handler IBMDERR. After handling the 
FINISH condition, IEMDERR branches to the 
GOTO code in the TCA to terminate the 
program. This is standard system action 
for the FINISH condition and for normal 
return from an ON FINISH on-unit. The GOTO 
code is given the address of the dummy DSA 
as the target DSA address. The abnormal 
GOTO out of block routine is thus enetered. 
This routine checks to see if any files are 
open and closes any that are. Any exit DSA 
processing (for example termination of 
SORT) is handled during this routine. 
Finally a test is made to discover whether 
IBMDPIR was called from the control 
program. If so, a test is made to discover 
whether the termination is the result of an 
ERROR condition. If the termination is 
caused by an ERROR condition, a CANCEL 
macro instruction is issued to ensure the 
flushing of any SYSIPT data. If the 
termination is not caused by an error 
condition, an EOJ macro instruction is 
issued to return to the control program. 
If there was a caller, IBMDPJR is called at 
entry point IBMBPJBC (see below) . 

IBMDPIR also contains certain, utility 
routines that may be used by all programs. 
These are the GOTO out of block routine 
described in chapter 2, and the code to 
acquire second and subsequent levels of 
library workspace. IBMDPIR also contains a 
CSECT PLIMAIN that is link-edited if an 
attempt is made to initialize a non-main 
PL/I procedure. This dummy PLIMAIN is 
link-edited because the compiler only 
generates a PLIMAIN control section for a 
main procedure. The dummy PLIMAIN contains 
code to load and call the module IBMDPEP. 
IBMDPEP puts out a message indicating that 
there is no main procedure and terminates 
the program. 

Initialization when a PL/I procedure is 
called from another language is similar 
except that the module IBMDPJR is used. 
This module contains the entry points 
PLICALLA and PLICALLB. 

The major difference between IBMDPIR and 
IBMDPJR is that IEMDPJR can be passed 
parameters indicating the size and the 
location provided for the ISA, and also a 
parameter list for the called procedure. 



Figure 5.2. Program management area 



IBMDPJR has four initialization entry 
points as follows: 
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PLICALLA ISA acquired is remainder of 

partition. Can pass parameter 
list to PL/I program. Control 
passed to procedure whose 
address is in PLIMAIN. 

PLICALLB ISA size and address must be 

specified. Can pass parameter 
list to compiled code. 
Control passed to procedure 
whose address is in PLIMAIN. 

IBMBPJRA ISA acquired is remainder of 

partition. Can pass parameter 
list to compield code. 
Control passed to routine 
whose address is in word 
addressed by register zero. 

IBMEPJRB ISA size and address must be 

specified. Can pass parameter 
list to compiled code. 
Control passed to routine 
whose address is in word 
addressed by register zero. 

A further entry point IBMBPJRC is used 
during termination. If the GOTO cut of 
block routine discovers that PL/I was 
called from another language it returns 
control to IBMBJRC which calculates a 
return code and restores the caller's STXIT 
options and program mask. IBMBPJRC then 
returns to the caller. 

IBMDPJR calls on the transient routine 
IBMDPJI to initialize the program 
management area, save the caller; s STXIT 
options and set up the PL/I STXIT options. 

When calling PL/I from another language 
via PLICALLA or PLICALLB it is necessary to 
explicitly include reference to IBMDPJR in 
the input to the linkage editor. For 
example by an INCLUDE IBMBPJRA statement. 
(Note that IBMBPJRA must be specified 
because this is the entry point name.) 



address the error-handling and storage- 
management routines, and to point to the 
current segment of dynamic storage. 

The TCA is the most important control 
block in the PL/I environment. A field-by- 
field description follows. 



Flags 



BOS 



EOS 



Indicate that an abnormal 
GOTO cut of block may take 
place (see below) . Also 
indicate that certain special 
error conditions may arise. 

The pointer that points to 
the beginning of the current 
segment (see chapter 6) . 

The pointer that points to 
the end of the current 
segment (see chapter 6) . 



Address of external save area: 

The address of the save area 
for the calling routine, if 
IBMDPIR was not called from 
the control program. 

Address of translate-and-test table 
for IBMDERR: 

See below, under heading 
"Translate-and-Test Table." 

Address of TCA appendage 

Address of save area for IBMBPGRC and 
IBMBPGRD (see below) 



Open file chain: 



Used when closing files at end 
of job 



PL/I and user return code: 



A standard area to keep these 
codes. 



THE PROGRAM MANAGEMENT AREA 



Address of IBMBPGEE: 



A diagram of the program management area is 
shown in figure 5.2. It shows the 
situation when the compiled program is 
called. The various fields in the program 
management area are shown in detail in 
appendix B. A brief description of their 
use is given below. 



Task Communicatipns_Area (TCA). 



The. TCA is the central communications block 
used throughout the program. It is used to 



Stack overflow routine for 
VDAs (see chapter 6) 

Address of the diagnostic file block (see 
below) 

Address of flow statement table: 

This is Used to address the 
flow statement table which 
holds statement numbers for 
use during execution. 

Address of tab table: 

The address of a table of 
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tabulator positions used in 
list-directed output. 

Address of FLOW module: 

The address of the module used 
to implement the compiler FLOW 
option. 

Address of storage-handling routines: 

Entry points to IBMDPGR that 
get non-LIFO storage, free 
non-LIFO storage, and acquire 
a new segment for LIFO storage 
(see chapter 6) . 

Address of IBMBERRB 

Address branched to after a 
software-detected interrupt 
occurs (see chapter 7) . 

Address of environment descriptor: 

Identifies release of compiler 
being used. 

Code for GOTO out of block: 

Whenever a GOTO out of block 
occurs, or could potentially 
occur because of the value of 
a label variable, compiled 
code branches to this code in 
the TCA, which calls a 
subroutine in IBMDPIB. The 
subroutine calls the flow and 
count module if either FLOW or 
COUNT is in effect and tests 
flags to see if an abnormal 
GOTO has occurred. The 
abnormal GOTO 

flags are set by compiled code 
or by library routines in 
which an abnormal GOTO could 
occur. (See, for example, 
description of SORT" in chapter 
11.) If the abnormal GOTO flag 
is set, the abnormal GOTO 
subroutine is called. 
Otherwise, the routine 
restores the value of register 
13 for the block to which a 
branch is being made, and also 
restores the values of 
registers 4 (the temporary 
base) and 3 (the static base) . 
Condition enablement is also 
restored, and NAB may require 
alteration if a variable data 
area (VDA) has been used. If 
necessary IBMBPGO is called to 
reset CHECK enablement. 
Finally, a branch is made to 
the correct location and the 
program base altered if this 
is necessary. 



| Address of count module 



Used to call IBMBEFLC when the 
COUNT option is in effect. 



Address of IBMBPGO 



Used in GOTO code see above 



Addresses of various routines: 



The TCA is completed with the 
address of the WAIT COMPLETION 
and Event assign routines. 
These are library routines 
that, for speed, are addressed 
from the TCA. The addresses 
are held as WXTRNs and are 
resolved if compiled code 
calls these modules. 



The fields to hold the address 
of the overflow routine, the 
environment descriptor, the 
GOTO code, and the error 
handler are duplicated. This 
allows version H of the 
compiler to use more efficient 
means of calling these 
routines and retains 
compatibility with previous 
versions. For details of the 
locations of TCA fields see 
Appendix B. 



TCA, Appendage (TIA) 



The TCA appendage is addressed from the 
standard part of the TCA (see above) . Its 
contents are as follows: 

Address of the byte beyond the ISA (TISA) : 

This holds the address beyond 
the end of the partition and 
is necessary because EOS gets 
altered when non-LIFO dynamic 
storage is allocated. 

Address of last free area (TLFE) : 

This points to a chain of 
areas of non-LIFO dynamic 
storage that have been freed, 
but cannot be amalgamated with 
the major free area. 



Flags 



Indicating: 
1. SYSPRINT is opened for 
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stream output (i.e., 
that it has been opened 
as expected and can be 
used for error 
messages) . 

That an abnormal 
termination is in 
progress. 

That dump I/O is in 
progress. 



Address of dummy DSA: 



Used, when abnormally 
terminating the program, to 
restore IBMDPIR's registers. 
This is faster than chaining 
back and testing for the dummy 
DSA, and allows IBMDPIE to be 
reached should the DSA chain 
become overwritten. 



Tab Table 



This is used to restore 
register 12 when a program 
check occurs, in case it has 
been changed by a non-PL/I 
subroutine. 



Forty bytes reserved for 
PLITABS (transient library 
module IBMBSTAB) . This CSECT 
is loaded when a STREAM PRINT 
file is opened or when PLIDUMP 
is called. It contains the 
linesize, tabulating positions 
and ether information for 
PRINT files. Only the 
pagesize is used for PLIDDMP. 



Save Area for IBMDEGR 



Address of get-library- workspace routine: 

This routine is part of the 
transient library module 
IBMDPIR and is used to get a 
new allocation of library 
workspace and an ONCA. This 
routine is called after 
interrupts and during program 
initialization (see chapter 
3) • 

Address of loaded-module chain: 



This area is used 
routine entered wh 
room for a further 
segment of the LI! 
library workspace 
IBMDPGR is require 
caller's save area 
yet been acquired, 
has a save area re 
management area. 



as a DSA for IBMDPGR, the 
en there is not enough 

DSA in the current 
stack. Both DSAs in 
may be in use when 
d, and there may be no 

because a DSA has not 
Consequently, IBMDPGR 
served in the program 



This is a chain of the names 
of transient library modules 
that have been loaded. It is 
kept to prevent duplicate 
loading. 

Code to handle interrupts and save area 
for STXIT: 

The STXIT macro requires a 
save area to use after a 
program check interrupt 
(program check) ; this is the 
area used. The code branches 
to the error-handling module 
IBMDERR. 



Dummy GNC A 



The dummy ONCA holds default values for the 
condition built-in functions. These will 
be supplied if they are requested either 
when no interrupt has occurred, or when no 
interrupt with the requested condition 
built-in function value has occurred. 
There is a chain back through all ONCAs to 
the dummy ONCA. (See chapter 7.) 



Translate-and-Test Table 



Address of interrupt handler (TERA) : 

This is the address to which 
the branch is made after a 
program check interrupt (see 
above) has occurred. 

Address of count tables 

These are used for 
implementing the COUNT option. 

Address of the TCA 



The translate-and-test table contains code 
used in error handling to identify relevant 
on-cells. (See chapter 7.) 



Diagnostic File Block 



The diagnostic file block holds information 
used by the error-message modules. This 
includes the address of the SYSPRINT 
transmitter. 
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Dummy., PSA 



Callerls_STXIT_02tigns 



The dummy DSA acts as a save area for the 
registers of the initialization routine 
IBMDPIR, and an end to the chain of DSAs 
when a search through blocks is being made, 
as for example, when searching for a 
relevant established on-unit (see chapter 
7) . The dummy DSA has a bit in its flag 
byte to indicate that it is a dummy. The 
dummy DSA contains a NAB (next available 
byte) pointer enabling the main procedure 
to obtain a DSA in the LIFO stack. 



Libr ar y,. Workspace (LJHS]_ 



This consists of two pre-f ormatted DSAs 
that are used by certain of the library 
modules. (See chapter 3.) 



ON Communicat io ns. Are a ,(QNCA) 



This is two words in which the caller's 
STXIT PC options are held. These are 
restored before a return is made. 



Op era ti on Interrupt. Ana lysis Code 



This is code placed in the program 
management area by IBMDPII. It is used by 
the error handler to test whether an 
operation interrupt has been caused by an 
attempt to execute a floating point 
instruction on a machine with no floating 
point hardware. 

During program initialization IBMDPII 
tests to see if the machine has floating 
point hardware. If it has, the code 
consists only of a direct return. If there 
is no floating point hardware on the 
machine, code to analyze the interrupt is 
placed in the program management area. 



The ONCA is supplied as an area where 
compiled code or library routines can store 
or read out any condition built-f unction 
values that may be reguired. (See chapter 
7.) 



The code is addressed from the TCA and 
is called by the error handler when an 
operation interrupt occurs. If the analysis 
shows that the error was due to lack of 
floating point hardware, a code is returned 
to the error handler. 
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Chapter 6: Storage Management 



The program compiled by the DOS PL/I 
Optimizing Compiler is executed in either a 
background partition or a foreground 
partition. The executable program phase is 
placed at the start of the partition. The 
remainder of the partition is known as the 
initial storage area (ISA) , and is used for 
various functions during execution. The 
start of the ISA is used as the program 
management area. This is an area that 
contains a number of housekeeping fields 
and is set up by the initialization routine 
IBMDPIR. (See chapter 5.) The remainder 
of the ISA is used for PL/I dynamic storage 
allocation. 

The contents of the executable program 
phase are described in chapters 2 and 5 of 
this publication. The contents of the 
program management area are described in 
chapter 5. This chapter is concerned with 
the allocation and freeing of PL/I dynamic 
storage. Information on storage handling 
during interlanguage communication is given 
in chapter 13. 



TYPES OF DYNAMIC STORAGE REQUIRED 



The reguirement for dynamic allocation and 
freeing of storage is inherent in the 
language. Automatic variables are 
allocated and freed on a block-by-block 
basis. Controlled and based variables can 
be allocated and freed by appropriate PL/I 
statements. Storage is also obtained 
dynamically for workspace, compiler- 
generated temporary values, I/O buffers, 
and PL/I transient library routines. 

Dynamic storage can be conveniently 
divided into two classes. 



A DSA is allocated for every procedure or 
block and contains: 

• The operating system standard save area. 

• Certain standard housekeeping fields. 

• All automatic variables and compiler- 
generated temporaries whose length is 
known during compilation. 

VDAs are acquired for all other allocations 
of LIFO dynamic storage. These are: 

• Storage for automatic variables and 
compiler-generated temporaries whose 
length is not known until execution. 
(DCL X CHAR(N), for example.) 

• Storage for those transiently-loaded 
library routines that can be freed 
immediately they have been used. (Open 
and dump routines, for example.) 

• Library workspace (LWS) and ON 
communication area (ONCA) acquired 
immediately before an on-unit is 
entered. 

• Workspace for certain library modules. 



Cont ents of Non-LIFO Storage 

Non-LIFO storage is used for the following: 

• Controlled variables. 

• Those based variables that are allocated 
by the ALLOCATE statement, provided that 
they are not allocated in a static or 
automatic area. 



1 . That which is allocated and freed on a 
last-in/first-out (LIFO) basis. 

2. That which is not. 

The first class is known as LIFO dynamic 
storage and the second class as non-LIFO 
dynamic storage. 



Contents of LIFO Storage 



Two kinds of storage area are allocated in 
LIFO storage. They are dynamic storage 
areas (DS As) and variable data areas (VDAs). 



• Such transient library routines as may 
be reguired more than once when they 
have been loaded. (I/O transmitters, for 
example) . 

• Input/output buffers. 



Dynamic Storage Allocation 



The principle used in dynamic storage 
allocation is to allocate LIFO storage from 
the low-address end of ISA, starting at the 
first 8-byte boundary beyond the program 
management area, and to allocate non-LIFO 
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/ 



Partition 



Executable 

Program 

Phase 



Program 

Management 

Area 



Head of free-area chain 
(TLFEinTCA) 



Main procedure DSA 



Subroutine DSA 



MAJOR FREE AREA 



3rd allocation for 
a controlled variable 






2nd allocation for 
a controlled variable 



1st allocation for 
a controlled variable 



End of partition 
Figure 6.1. The principles of dynamic storage allocation 



LIFO storage 

Held in a contiguous 
stack, starting at the 
address following the 
program management area. 
Elements can be freed 
only from the high-address 
end of the stack. 



Non-L I FO storage 

Held in a stack starting 
at the high-address end 
of the partition. Any 
element in the stack can 
be freed; consequently, 
all elements are not 
necessarily contiguous. 
When elements are freed, 
they are placed on a 
free-area chain and used 
ifor subsequent 
allocations, if possible. 



storage from the high-address end of the 
ISA, which is also the high-address end of 
the partition. All storage is allocated in 
multiples of 8 bytes. Between the areas of 
LIFO and non-LIFO storage is an unused 
section known as the ma ~| or. free area. (See 
figure 6.1.) 

The last element in the LIFO stack is 
always the first to be freed and 
consequently can always be amalgamated with 
the major free area. This is not always 



the case with non-LIFO storage. When an 
item not contiguous with the major free 
area in the non-LIFO stack is freed, it is 
placed on a free-area chain whose head is 
anchored in the TCA. Attempts are always 
made to use areas on this chain when 
further allocations of non-LIFO storage are 
made. 

Allocations of LIFO storage are made by 
testing to see if there is enough space in 
the major free area. If there is not 
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enough space, an attempt is made to use an 
area on the free-area chain. When an area 
on the free-area chain is used, it is known 
as a new segment of the LIFO stack. 



freed but that could not be amalgamated 
with the major free area. The start of the 
chain is held at offset 8 (TLFE) in the TCA 
appendage and points to that element with 
the highest address. 



Handling 

To keep track of the storage allocated and 
freed, a number of pointers are used. 
These are: 

• The begining-of-segment pointer (BOS) . 

• The end-of-segment pointer (EOS) . 

• The next-available-byte pointer (NAB) . 

• The free-area chain. 

• A pointer to the byte beyond the end of 
the ISA (TISA) . 

The be qinninq-of- segme nt po inter (BOS) is 
initially set during program initialization 
to point to the start of the ISA. It is 
not altered unless a new segment of storage 
is acguired. BOS always points to the 
start of the current storage segment. BOS 
is held at offset 8 from the head of the 
TCA, and is addressed from register 12. 

The end-of-segment pointer (EOS ) is 
initially set during program initialization 
to point to the end of the ISA. However, 
it is updated, when non-LIFO storage is 
allocated, to point to the end of the major 
free area. EOS -is held at offset X 1 ^ (12) 
in the TCA, and is addressed from register 
12. 

Thene xt- ayailabl e-byt e poi nter (NAB) is 
held in every DSA and points to the first 
8-byte boundary beyond the DSA (or VDA if 
one has been acguired) . This address is 
the start of the major free area. The 
current NAB is held in the most recent DSA 
and is addressed from offset X'4C»(76) from 
register 13. As register 13 is altered 
every time a DSA is acguired, the value in 
a NAB pointer need only be altered when a 
VDA is freed or acguired. Previous NABs 
are automatically restored when register 13 
is pointed to a previous DSA. 

The pointer to the byte beyond th e ISA 
(TISA) is used to keep track of the end of 
the ISA. 

The first two bytes of BOS, EOS, and NAB 
contain segment numbers ("FF" for the ISA) . 
The use of these numbers is explained under 
"Acguiring a New Segment." 

The free-area chain includes those elements 
of non-LIFO dynamic storage that have been 



ALLOCATING AND FREEING LIFO STORAGE 



Allocating and freeing LIFO storage is 
handled by compiled code or by the 
particular library module that reguires the 
space. The allocation is done in the 
manner used by the prologue code shown in 
chapter 2. Freeing is done in the manner 
used by the epilogue code, which is also 
shown in chapter 2. Before allocating the 
storage, a test is made to see if there is 
enough space in the major free area for the 
new allocation. This test is carried out by 
logical arithmetic, for reasons explained 
later, under the heading "Acguiring a New 
Segment." If there is not enough room, 
entry jto the segment-handling entry point 
of the resident library module IBMDPGR is 
made. The address of this entry point is 
held at offset X»74» (116) in the TCA. The 
allocation of LIFO storage involves finding 
the current NAB. This gives the address of 
the start of storage to be used. A new 
value of NAB is calculated, addressing the 
byte beyond the end of the new allocation. 
Freeing the storage is done by restoring 
the NAB pointer to the previous value. 
Figure 6.2 illustrates the principles 
involved. Before allocating the storage, a 
test is made to see if there is enough 
space for the allocation. 



ALLOCATING AND FREEING NON-LIFO STORAGE 



Any section of non-LIFO storage can be 
freed at any time; therefore a simple 
stacking mechanism cannot be used, because 
it would waste storage by leaving freed 
storage within the stack. A modified 
method is therefore used. When storage 
that is contiguous with the major free area 
is freed, it is amalgamated with the major 
free area by altering the end-of-segment 
pointer, which indicates the end of this 
area. When storage that is not contiguous 
with the major free area is freed, it is 
placed on the free-area chain, which is 
anchored to a field in the TCA. Whenever 
an allocation is made, an attempt is made 
to place the allocation in an area that is 
already on the chain, rather than use a 
further section of the major free area. 
Allocations of non-LIFO dynamic storage are 
always handled by the library module 
IBMDPGR, whose address is held in the TCA. 
Figure 6.3 illustrates the principles 
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To dummy DSA 

A 

I R13 |> 



R13- 

(=old NAB) 



Backchain (stored at fixed offset from R13) 



Main procedure DSA 



NAB (stored at fixed offset from R13) 



<h 



Backchain (= old R13) 



Subroutine DSA 



NAB 



_1 



EOS 



Allocating a new DSA 



1. Test if major free area large 
enough for new DSA. If not 
call IBMBPGRC. 

2. Store R 13 at fixed offset from 
old NAB to act as backchain . 

3. Load R 1 3 with address of old NAB. 

4. Store new NAB at fixed offset 
from register R13. 



Freeing a DSA 



Load register 13 with current 
backchain address. Since the 
NAB and backchain fields are 
always addressed from register 
13, the previous values are 
automatically restored. 



Figure 6.2. Principles involved in allocating and freeing LIFO storage 
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2. Allocate by altering 


2. 


Is area next to an 




will hold new allocation. 
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area already on 
free-area chain? No. 




Allocate at high-address 
end, leaving remaining 




3. 


Place area on free- 




area on free-area chain. 






area chain. 


3. 


Alter length field at head 
of remaining area. 



Figure 6.3. Principles involved in allocating and freeing non-LIFO storage 



involved. Whenever an allocation within 
the major free area is made, the end-of- 
segment pointer, in the TCA, is updated to 
point to the end of the major free area. 

If there is insufficient space for an 
allocation of non-LIFO storage either in 
the major free area or in an area on the 
free-area chain, the program is terminated. 



ACQUIRING A NEW SEGMENT OF LIFO STORAGE 



Every time a new procedure or block is 
entered, or a VDA is acguired, a test is 
made to see whether there is enough space, 
for the DSA or VDA, between the NAB pointer 
and the EOS pointer. If there is not 
enough space then an attempt is made to use 
the largest space on the free-area chain. 



Pointers BOS and EOS are set to point to 
the beginning and end, respectively, of the 
new segment. The DSA or VDA is allocated 
in the low-address end of the segment, and 
the NAB pointer is set to point to the 
first free byte after the DSA or VDA. The 
former values of BOS and EOS are stored at 
the start of the new segment. 

A segment number is given to each 
segment, starting at hexadecimal "FF" and 
reducing by 1 for each new segment. The 
number for the ISA is "FF", the second 
segment "FE", and so on. This number is 
held as the first byte of the NAB, BOS, and 
EOS pointers. The result of this device is 
that when logical arithmetic is used, all 
addresses in later segments are apparently 
less than those in the earlier segments, 
regardless of their actual position. This 
simplifies segment handling. For instance, 
when a DSA in the second segment is freed. 
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NAB is simply restored to its previous 
value which may well be in the first 

segment. NAB will then hold value "FF 

» r and EOS the value »FE ". When a 

further DSA is required, EOS will be less 
than the sum of NAB and the DSA length, as 
NAB is already greater than EOS. 
Consequently it will appear that there is 
insufficient space for the DSA in the first 
segment, regardless of whether or not this 
is the case. The library module IBMDPGR is 
thus called to restore BOS and EOS, 
rearrange the free-area chain, and if 
possible place the new DSA after NAB in the 
first segment. The process is illustrated 
in figure 6.4. 



IBMDPGR - STORAGE MANAGEMENT ROUTINE 



The allocation and freeing of LIFO storage 
within a given segment is handled by 
compiled code or by the library module 
reguiring the storage. All other dynamic 
storage allocation is carried out by the 
resident library routine IBMDPGR; this 
module has four entry points: 

IBMBPGRA Allocating non-LIFO storage. 

IBMBPGRB Freeing non-LIFO storage. 

IBMBPGRC Obtaining and freeing additional 
storage segments (for DSAs) . 

IBMBPGRD Obtaining and freeing additional 
storage segments (for VDAs) . 

These four entry points are described 
below. 



Allocating Non-LIFO Storage (IBMBPGRA) 



allocated. 



Freeing Non-L IFO Storage .jIB-tf BPG RB) 



When entered by IBMBPGRB, the module scans 
the free-area chain (if one exists) to see 
whether the storage being freed can be 
amalgamated with areas already on the 
chain. This is done if possible. The 
module then checks to see whether the 
storage being freed is adjacent to the 
major free area. If so, EOS is altered to 
point to the end of the area being freed or 
to the end of the amalgamated area, if this 
adjoins the major free area. If neither 
case applies, the area is added to the 
free-area chain, which is arranged in 
descending order of addresses. 



S egmen t Ha ndlin g ( IBMBPG RC a nd 
IBMBPGRD) 



When compiled code discovers that the 
address contained in the NAB pointer plus 
the length of the area to be allocated is 
greater than the value of the pointer EOS, 
either IBMDPGRC or IBMDPGRD is called, 
depending on whether a new DSA or VDA is 
required. 

The entry points are called in two 
circumstances: 

1. There is insufficient room in the 
current segment for allocation of the 
DSA or VDA and, consequently, a new 
segment is required. 

2. A segment other than the first one has 
been allocated, but is no longer in 
use. 



When entered by entry point IBMBPGRA, the 
module first frees any LIFO segments that 
are not in use, searches the free-area 
chain, if one exists, and allocates the 
storage in the smallest possible area on 
the chain. If an area of the exact size is 
found, it is removed from the chain; 
otherwise the length stored in the first 
word of the area is altered. If there is 
no chain, or no area on the chain that is 
large enough, IBMDPGR attempts to allocate 
the storage in the area immediately 
preceding the EOS pointer. If there is not 
enough space between the EOS pointer and 
the current NAB pointer, the program is 
terminated. 

Provided that storage can be allocated, 
control is passed back, with register 1 
pointing to the address of the storage 



IBMBPGRC and IBMBPGRD check to see which 
of the above two situations caused the 
call. This is done by checking whether the 
number in the first byte of NAB is greater 
than the number in the first byte of EOS. 

In case 1 above, the segment numbers are 
the same, and a new segment must be 
allocated. A new segment is allocated by 
searching the free-area chain for the 
largest available area and using this as a 
new segment. If there is no area large 
enough to hold the new DSA, control returns 
to IBMDPIR, which calls module IBMDPES to 
generate an "insufficient storage" message, 
and then terminates the program. If a new 
segment is allocated, the old values of BOS 
and EOS are placed in control words at the 
head of the new segment. New values for 
BOS and EOS, with first byte numbers 
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Initial situation 

1. Free-area chain exists. 
BOS, NAB, and EOS have 
X'FF' in first byte, i.e., 
segment number 1 . 



Figure 6.4- Segment handling 



Acquiring new segment 

1 . Compiled code or library 
routine finds major free 
areas too small. Calls 
IBMBGR. 

2. IBMBGR finds an area on 
free-area chain large 
enough for allocation. 

3. Stores old BOS and EOS. 
Sets new BOS and EOS, and 
returns to caller. 

4. Caller gets new DSA. 
BOS, EOS, and NAB have 
X'FE' in first byte, i.e., 
segment number 2. 



Freeing DSA in segment 

1 . Register 1 3 is restored in 
the normal way. BOS and 
EOS are not restored. The 
segment will not be freed 
until there is a further 
demand for storage, that 
can be accommodated 

in the previous segment. 

2. NAB now has X'FF' in first 
byte, BOS and EOS still 
have X'FE'. 



Freeing segment 

1 . When storage is again required, 
NAB + storage required is 
compared with EOS using 
logical arithmetic. 

2. NAB + storage is found to be 
greater (because of different 
segment numbers), so IBMBGR 
is called. 

3. IBMBGR finds segment 
numbers are different. Tests to 
see if new storage will fit in old 
segment. If not, allocates in 
current segment. 

4. Storage will fit, so restores old 
BOS and EOS, places segment 
on free-area chain, and returns 
to caller. 

5. Caller allocates storage starting 
at current NAB. 



SO 



decremented by one, are placed in the TCA. 
The address of the new NAB is passed in 
register zero; the address for the start of 
the new DSA or VDA is passed in register 1. 

In case 2 above, the number in the first 
byte of NAB is greater than the number in 
the first byte of EOS. If the difference is 
greater than one, then more than one extra 
segment has been allocated for DSAs which 
are no longer current. In this case, 
segments are freed until only one empty 
segment remains. This is done by setting 
BOS and EOS to the values held in the 
control words at the head of each segment 
and freeing the storage in the way 
described for IBMBPGRB above. 

When only one empty segment remains, a 
test is made to see whether the new DSA 
Will fit into the segment that contains the 
present NAB pointer (the segment before the 
empty segment) . This test is made by 
comparing the current NAB pointer with the 
old EOS pointer held in the control words 
of the empty segment. If there is 
sufficient room, the empty segment is freed 
as described under IBMBPGRB, above. Return 
is then made to the caller with a new value 
for EOS and BOS, and the DSA is allocated 
immediately after the old NAB. 

If there is not enough room in the 
segment containing NAB, then a test is made 
to see if the empty segment is large enough 
to hold the new DSA. This is done by 
comparing the difference between the 
current BOS and EOS with the length of the 
element. If there is enough room, the DSA 
is allocated in the empty segment. The 
address of the start of the storage is 
passed to compiled code in general register 
1 and the address of the new NAB in general 
register 0. 

If there is not enough room in the empty 
segment, then the segment is freed. There 
are now no empty segments, and the 
situation is treated as if there had been 
no empty segments in the first place. 

Note: It is possible that after freeing a 
number of empty segments, an area on the 
free-area chain can immediately follow EOS. 



However, the possibility is remote, and no 
check is made to see whether this is the 
case. 



Storage Management in Programmer- 
Allocated Areas 



By using area variables, PL/I allows the 
programmer to use a continuous area of 
storage for based variables. The 
allocation of storage for area variables is 
handled in the same way as that for other 
types of variable, and depends on the 
variable's storage class. The allocation 
and freeing of storage within an area is 
handled by the library module IBMBPAM. 

If there is not enough space for an 
allocation or if the target area is too 
small in an assignment statement, the AREA 
condition is raised. 

The method employed is that storage is 
allocated from the low-address end of the 
area, and an offset is kept to the end of 
the item with the highest address allocated 
in that area. This offset is known as OEE 
(offset to end of extent) . When storage is 
freed, either the OEE is altered or the 
storage is placed on a free-storage chain, 
with the largest segment at the start of 
the chain. The method used is conceptually 
the same as that used for non-LIFO storage. 
However, the chain is held in a different 
order and the stack extended in the 
opposite direction. If a space freed is 
adjacent to any that are already free, the 
spaces involved are amalgamated into one. 
This is done either by altering OEE, or 
combining the new free space with one or 
more free spaces that are already in the 
free chain, or possibly by a combination of 
these methods. When a free chain exists, 
IBMBPAM always attempts to allocate storage 
by using a space on the chain. The low- 
address end of the smallest possible space 
on the chain is used, and the chain is then 
rearranged to maintain the correct order of 
decreasing size. 
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Chapter 7: Error and Condition Handling 



This chapter deals with the method used to 
implement execution-time error handling. 
Many errors detected at execution time are 
related to PL/I conditions and can be 
handled either by on-units written by the 
programmer, or by standard system action. 
The chapter starts with a summary of the 
error and PL/I condition handling 
facilities offered by the PL/I language. 
The implementation problems these 
facilities raise, and the methods used to 
handle them, are then described. An example 
of error handling is given which allows the 
principles involved to be followed through 
in a program. The chapter finishes with a 
brief description of the error message 
modules, the modules used to implement the 
PLIDUMP facility, and other debugging 
facilities. 



Summary of PL/I Error Handling 



A table showing all PL/I conditions, and 
the method by which they are detected, is 
given in figure 7.2. 



Hardware interrupt | PL/I condition 



Operation 




Privileged operation 




Execute 




Protection 


EEBOE 


Addressing 


(after issuing 


Specification 


a message) 


Data 




Fixed point overflow 


FIXEDOVEEFLOW/SIZE 


Fixed point divide 


ZEEODIVIDE/SIZE 


Decimal overflow 


FIXEDOVEEFLOW/SIZE 


Decimal divide 


ZEEODIVIDE 


Exponent overflow 


OVEBFLOW/SIZE 


Exponent underflow 


UNDERFLOW 


Floating point divide 


ZEEODIVIDE 



L -J 



PL/I allows the programmer to obtain 
control after the occurrence of any PL/I 
interrupt. A PL/I interrupt is defined as 
"the redirection of flow of control of a 
program, as the result of the raising of .an 
enabled PL/I condition. " A PL/I interrupt 
is not the same as a program check 
interrupt, although all program check 
interrupts, other than "significance" and 
certain input/output interrupts, can, and 
normally do, cause PL/I interrupts. (See 
figure 7.1.) PL/I interrupts are always 
associated with PL/I conditions. They fall 
into three classes: 

1. Hardware interrupts (program checks) 
which are interpreted as PL/I 
conditions and treated as PL/I 
interrupts. See figure 7.1. 

2. Special PL/I error conditions that 
have no equivalent at the program 
check level. For example: CONVEBSION 
and SDBSCEIPTRANGE. 

3. PL/I conditions that are not errors, 
but occur at unpredictable times 
during the program; for example, 
ENDFILE and ENDPAGE. 

Throughout this chapter, interrupts and 
PL/I conditions recognized by the system, 
are referred to as program ., check 
interrup ts. Interrupts detected by 
checking code at the PL/I level are 
referred to as software-detected 
interrupts, or software interrupts . 



Figure 7.1. Hardware interrupts 
associated with PL/I conditions 



The programmer has the choice of 
defining the action that will be taken when 
a PL/I interrupt occurs, by writing an on- 
unit for the relevant condition, or of 
accepting the default action. This default 
action is known as standard system action . 
If control has passed through an 0N- 
statement (that has not been overriden by a 
EEVEET or other statement) , the associated 
on-unit is said to be established . 

The programmer also has the choice of 
whether or not certain of the PL/I 
conditions shall cause PL/I interrupts when 
they occur. When a condition causes a PL/I 
interrupt, it is said to be enable d. When 
it does not cause a PL/I interrupt, it is 
said to be di sable d. Some conditions are 
enabled by default; some are disabled by 
default. Details are shown in figure 7.2. 
Many of the conditions whose enablement is 
under programmer control are error 
conditions that are peculiar to the PL/I 
language. Because these interrupts are not 
recognized by the system, special* 4 code has 
to be generated if they are to be 
recognized. PL/I, therefore, gives the 
programmer a choice of whether to have this 
code generated and have more efficient 
debugging aids at his disposal, or of not 
having the code generated, and having a 
faster and shorter program. Normally, 
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relevant conditions will be enabled during 
the testing of a program and removed for 
production runs. Conditions whose 
enablement is under programmer control can 
be enabled or disabled for the duration of 
a statement or a block* 

Certain of the program check interrupts 
can be disabled by the programmer. When 
this is done, the interrupts still occur at 
system level. They are intercepted before 
PL/I interrupts occur, and control is 
returned to the point of interrupt. 

A number of further factors influence 
the implementation of error handling. 
These factors are discussed below. 



Condition Built-in Functions 



PL/I defines a number of condition built-in 
functions and pseudovariables that allow 
the program to inspect the causes of an 
interrupt and, in certain cases, to alter 
the fields involved. These built-in 
function values are placed in a special 
control block known as the ONCA (ON 
communications area) before the main error- 
handling code is entered. 

Because any number of levels of 
interrupt can occur, a new ONCA is provided 
for every level of interrupt. This is done 
at the same time as a new allocation of 
library workspace is made. 



The ERROR Condition 



Static_and Dynamic Scope 



On-units have dynamic scope. That is, each 
procedure or block inherits the on-units 
established in the block that calls it, 
unless such on-units are specifically 
overridden. Thus, as the sequence in which 
procedures are called may depend on the 
input data, it is not always possible at 
compile time to predict which on-units will 
be applicable to any given section of the 
program. A method is therefore needed to 
determine this during execution. 

Condition prefixes have static scope. 
That is, they are inherited from the 
encompassing procedure or block in the 
source program. Thus, the enablement or 
otherwise of a condition is predictable at 
compile time. 



Levels of In terrupt 



An important concept in the understanding 
of error handling is that of levels of 
interrupt. With a few minor exceptions, 
the language allows any statements to be 
executed in on-units, but stipulates that 
the environment of the original interrupt 
must be retained so that a return can be 
made to the point of interrupt when the on- 
unit is completed. This necessitates a 
further allocation of library workspace for 
use during the on-unit, as the original 
allocation may be in use when the interrupt 
occurs and cannot be overwritten. As there 
may be PL/I interrupts during the execution 
of on-units, the stacking of levels of 
library workspace can, theoretically, 
continue indefinitely. 



The ERROR condition is raised as standard 
system action for those PL/I conditions 
that will normally be caused only by 
errors. (See figure 7.2 for details.) It 
is also raised by certain program check 
interrupts (see figure 7.1), and a number 
of software-detected interrupts that have 
no directly-associated PL/I condition. A 
message is generated before the condition 
is raised. This is beyond the control of 
the programmer, and the message will be 
produced regardless of the presence of an 
ERROR on-unit. 



The Implementation of Error Handling 



The most important points in the error- 
handling scheme are the following: 

1» During compil ation , the compiler 
generates code to check for the 
various PL/I conditions that are not 
related to program check interrupts 
or, alternatively, code to call 
appropriate library modules that will 
check for these conditions when they 
carry out the required function. 

2. During pr ogram initialization , the 

initialization module IBMDPII issues a 
STXIT macro instruction, which results 
in the system passing control to the 
error-handling routine IBMDERR, 
whenever a program check (hardware- 
detected interrupt) occurs. 

3» Durin g execution. The PL/I resident 
library module IBUDERR gains control 
whenever a PL/I condition is 
recognized, or a program check 
interrupt associated with a PL/I 
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Name of 
condition 


Qual- 
ified 


Description 


Recognized by 


Default 


Program 

-mer 

Control 


ERROR** 
Condition 


Computational 
















CONVERSION 


no 


Attempt to 
convert invalid 
character string 


Code in 
library 


relevant 
modules 


enabled 


yes 


yes 


FIXEDOVEEFLOW 


no 


Overflow of a 
fixed point 
value 


System 




enabled 


yes 


yes 


SIZE 


no 


Attempt to 
assign too large 
a value 


Compiler-generated 
checking code, or 
program system 


disabled 


yes 


yes 


OVERFLOW 


no 


Overflow of a * 

floating-point 

value 


System 




enabled 


yes 


yes 


UNDERFLOW 


no 


Exponent becomes 
smaller than 
permitted 
minimum 


System 




enabled 


yes 


no 


ZERODIVIDE 


no 


Attempt to 
divide by zero 


System 




enabled 


yes 


yes 


Input/Output 
















ENDFILE 


yes 


End of file 
reached 


Code in 
library 


relevant 
modules 


enabled 


no 


yes 


ENDPAGE 


yes 


End of a page on 
a print file 
reached 


Code in 
library 


relevant 
modules 


enabled 


no 


no 


TRANSMIT 


yes 


Transmission 
error on a file 


Code in 
modules 


library 


enabled 


no 


yes 


UNDEFINEDFILE 


yes 


Error in opening 
file 


Code in 
library 


relevant 
modules 


enabled 


no 


yes 


KEY 


yes 


Invalid key 


Code in 
library 


relevant 
modules 


enabled 


no 


yes 


NAME 


yes 


Unrecognizable 
data- directed 
input 


Code in 
library 


relevant 
modules 


enabled 


no 


no 


RECORD 


yes 


Incorrect size 
record 


Code in 
library 


relevant 
modules 


enabled 


no 


yes 



** The ERROR condition is raised when an error occurs that is not covered by PL/I 
exceptional conditions - taking the sguare root of a real negative number, for 
example. It is also raised as standard system action when handling all types of 
error conditions. Thus an ERROR on-unit enables the programmer to intercept all 
error conditions. 



Figure 7.2. (Part 1 of 2) . PL/I conditions 
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| Name of |Qual-| Description | Recognized by | Default |Program| 

| Condition |ified| I I |-mer | ERROR** 

III | | | control | condition 


J Procrram Checkoutl 1 1 1 1 1 


| SUBSCRIPTRANGE | no j Array subscript | Compiler-generated | disabled | yes | yes 
| 1 | outside declared! checking code | | | 
| | (bounds j I || 

| STRINGSIZE | no | Attempt to |Code in relevant | disabled | yes | no 
| | | assign string | library modules | | | 
j | jto smaller | III 
| | | string | III 

| STRINGRANGE j no j Attempt to |Code in relevant* | disabled | yes | no 

| | (access beyond | library modules | | | 

| 1 j limits of string | I | | 

| CHECK | yes lvalue assigned j Compiler-generated j disabled | yes j no 

| (variable or | | to identifier or | j checking code, or | | | 

| label) | | control passed (library module | 1 1 

| | | through label | III 


1 List Processing | | I III 

| AREA | no | Attempt to | Relevant library | enabled | no j yes 
| 1 | allocate beyond | modules I | | 

| (I end of area | III 

■ j _ _ __ .. _ 


1 System Action | | I III 

I ERROR j no 1 1 Any error j Relevant library ( enabled | no j - 
I | | condition | modules I | | 
| | 1 1 including those | I II 
I j jnot covered by | III 
I | | other | I || 
I | | conditions** | III 

| FINISH | no 1 1 Program about to | Relevant library | enabled j no | 
| | | be terminated | modules I | | 


1 Programmer, Named! | | | | | 

| CONDITION j no | Programmer | Signal I enabled j no | 
| (name) j | defined | statement ( (when | | 
I I | condition | I coded) | | 


I * When STRINGRANGE is enabled, library modules are always called to handle substring 
| operations. These modules have the necessary code for checking for the STRINGRANGE 
| condition. 

(** The ERROR condition is raised when an error occurs that is not covered by PL/I 
1 exceptional conditions - taking the sguare root of a real negative number, for 
| example. It is alsp raised as standard system action when handling all types of 
| error conditions. Thus an ERROR on-unit enables the programmer to intercept all 
| error conditions. 



Figure 7.2. (Part 2 of 2) . PL/I conditions 
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condition occurs. This module checks 
to see if the associated PL/I 
condition is enabled and, if it is 
not, returns control to the point of 
interrupt. If the condition is 
enabled, the module then searches for 
a relevant, established on-unit, 
passing control to the first one that 
is found. If no established on-unit 
is found, IBMDEBE carries out the 
standard system action, calling any 
library modules necessary to do this. 



INFORMATION REQUIRED AT INTERRUPT 



Byte 1 holds a number which uniquely 
identifies the type of error or condition. 
Byte 2 is used to indicate the oncode and 
message associated with the error or 
condition. When bytes 3 and 4 are present, 
they are used to indicate which condition 
built-in functions may be required, and are 
copied into the flag byte in the current 
ONCA. 

The error code is generated by the 
object program or library module, for 
software-detected PL/I conditions, and by 
the error handler itself for hardware- 
detected interrupts. 



For the error-handling module to carry out 
the various functions necessary, the 
following information must be available. 

1. The type of PL/I condition that has 
occurred and the associated on-code. 

2. Whether the condition is one that can 
be enabled or disabled by the 
programmer and, if it is such a 
condition, whether it is enabled or 
disabled. 

3. Whether there is an established on- 
unit that applies to this condition. 

4. The values that may be used by any on- 
unit built-in function that appears in 
the on-unit. 

5. The standard system action for the 
condition. 



Enable Cells 



Enable cells are held at a fixed offset in 
each DSA. They are a set of flags that 
correspond to the PL/I conditions whose 
enablement can be controlled by the 
programmer. The PL/I conditions referred to 
are as follows: 



Bit 
Bit 1 
Bit 
Bit 
Bit 
Bit 
Bit 
Bit 
Bit 8 
Bit 9 
Bit 10 
Bit 11 



CHECK* 

ZERODIVIDE 

FIXEDOVERFLOW 

SIZE 

CONVERSION 

OVERFLOW 

UNDERFLOW 

STRINGSIZE 

STRINGRANGE 

SUBSCRIPTRANGE 

CHECK* 

CHECK* 



THE FIELDS USED IN ERROR HANDLING 



The fields used in accessing this 
information are the following: the error 
code, enable cells, ONCBs (ON control 
blocks) , ONCAs (ON communications areas) , 
and translate-and-test table in the TCA. 
The fields are shown in figure 7.3 and an 
example of error handling given in figure 
7.4. Appendix B contains diagrams of these 
fields. 



The Error Code 



*See section on handling CHECK for details. 

A flag is set to zero when the relevant 
condition is enabled. Two sets of these 
flags are held in each DSA - the block 
enable cells and the current enable cells. 
The block enable cells indicate the 
situation at the start of the procedure or 
block. The current enable cells show the 
position at the point in the program that 
is currently being executed. Having two 
sets simplifies resetting the flags when 
enablement is changed for a single 
statement. It also simplifies resetting of 
the enable cells should the statement 
result in entry to an on-unit or function 
reference, and simplifies return of control 
to a different part of the block because of 
a GOTO in the on-unit or function. 



The error code is either a four-byte or 
two-byte code. A four-byte code is 
generated when a PL/I condition is detected 
by compiled code. A two-byte code is 
generated when an error has been detected 
that does not have an immediately 
associated PL/I condition. 



ONCBs (ON Control Blocks) 



ON control blocks are used to address the 
on-unit and hold various information about 
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UNQUALIFIED CONDITIONS 



DSA 



LWS 



1 . A flag at the head of the DSA indicates that static ONCBs exist for that 
block. 

2 the block and current enable cells indicate which of those conditions that 
are under programmer control are enabled at any given point in the program. 
Each such condition is represented by a single bit in each cell. 

3. There is an on-cell for every ON-statement in the block. Each on-cell consists 

of a one-byte code identifying the condition, e.g., X'OA' (SUBSCRIPTRANGE). 
If the same condition appears more than once, previous on-cells are set to 
zero. 

4. Static ONCBs are held contiguously in static storage, in the same order as the 
corresponding on-cells. They contain a code byte and flags that indicate such 
things as : whether SYSTEM was specified, whether SNAP was specified, 
whether the on-unit consists of a single GOTO statement, whether it is a null 
on-unit etc. If there is an on-unit, its address is given in the second byte. (For 
GOTO-only on-units, the offset of the address of the label variable is given.) 



QUALIFIED CONDITIONS 



1 . A flag at the head of the DSA indicates that dynamic ONCBs exist. 

2. Dynamic ONCBs are set up during execution of each block in which qualified 
condition ON-statements occur. The last two words of a dynamic ONCB 
contain the same type of information as static ONCBs (described above, under 
'Unqualified Conditions'), but use additional flags to indicate whether the 
condition is enabled and whether it is established. The second word contains 
qualifying information, such as the address of the FCB (for conditions such 
asENDFILE, RECORD, TRANSMIT, KEY, etc.), or address of a symbol 
table (for ON CHECK on-units). 

3 Dynamic ONCBs are chained together, the most recent being addressed from 
a fixed offset in the DSA. The last dynamic ONCB in the chain contains zero 
in its backchain field. 
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Figure 7.3. The principal fields used in error handling 



the on-unit, for example, whether or not it 
is a null on-unit. 

1« Dynamic ONCBs: Dynamic ON control 

blocks are held in dynamic storage and 
are used for conditions that need 
qualification - ENDFILE, ENDPAGE, KEY, 
NAME, RECORD, TRANSMIT, UNDEFINEDFILE, 
CHECK, and the CONDITION condition. 
The dynamic ONCBs for each block are 
chained together, and the address of 
the first dynamic ONCB is held at 
offset X«60'(96) in the DSA of each 
block. One ONCB is generated for each 
condition and gualifier regardless of 
the number of ON-statements in the 
block for that condition and 
qualifier. Dynamic ONCBs, but not 
static ONCBs, are used to test if 
there is a relevant established on- 
unit for the condition and gualifier. 

2. Static ONCBs: Static ONCBs are held 
contiguously in static storage and 
refer to conditions that do not need 
qualification. A static ONCB is 
generated for every ON-statement in 
the block and holds the address of the 
associated on-unit if there is one. 
Each ONCB is associated with an oncell 
held in the DSA of the associated 
block. On-cells and ONCBs are held in 
the same order. The error-handling 
module searches the on-cells, counting 
how many on-cells it tests before the 
relevant on-cell is reached. The 
static ONCB is addressed by an offset 
from the address of the first static 
ONCB. The offset is calculated by 
multiplying the count of on-cells by 
eight, the length of a static ONCB. 
The address of the first static ONCB 
is held at offset X« 5C» (92) in the 
DSA. 

The addresses of the ONCBs are held at 
fixed offsets in the DSA. Dynamic ONCBs 
are chained together. Static ONCBs are 
held contiguously and can be found by 
incrementing the value of the first address 
until the correct ONCB is reached. 



ONCA ( ON Communications Area ) 



certain circumstances, be defined more 
accurately than on-codes allow. On-codes 
are compatible with those used in previous 
PL/I compilers. 



Du mmy ONCA 



ONCAs are chained together, so that a 
search can be made for the correct 
condition built-in function values through 
various levels of interrupt. The dummy 
ONCA, held in the program management area, 
acts as an effective end to the chain, and 
contains the default values for condition 
built-in functions. 



Dumnn 



The dummy DSA is not set-up exclusively for 
the use of the error-handling module. 
However, it plays an important part in 
error handling. After an interrupt, all 
existing DSAs are searched for an 
established on-unit that corresponds to the 
interrupt. The dummy DSA acts as an end in 
the chain that is searched. When the dummy 
DSA has been reached, standard system 
action is taken. 

The dummy DSA is also used to avoid the 
need for providing special-case code when 
calculating the address of the interrupt, 
and the name of the entry point, when an 
interrupt has occurred in the main 
procedure. 



Translate-and-Test Table 



When an unqualified condition has been 
raised, the translate-and-test table in the 
TCA is used by a translate-and-test (TRT) 
instruction to test the on-cells and see if 
a relevant on-unit is established. 



The ON communications area contains fields 
to hold the values, or address of the 
values, of any condition built-in functions 
that may be used. Flags are set to indicate 
which values are valid for the particular 
interrupt. The appropriate data is placed 
in the ONCA by compiled code or library 
modules. The on-code is not generated 
until required. Instead an error code is 
used. This gives greater flexibility in 
generating messages, as the error can, in 



Executing ON and REVERT Statements 



Executing ON and REVERT statements is 
essentially a matter of setting a flag, 
either on or off, in an on-cell or in a 
dynamic ONCB. The action depends on 
whether the associated PL/I condition is 
qualified or not, and hence whether an on- 
cell or a dynamic ONCB contains the flaq. 
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(SUBSCRIPTRANGE) : SORT: 

PROCEDURE OPTIONS (MAIN); 

ON SUBSCRIPTRANGE BEGIN; 

PUT EDIT ('SUBSCRIPTRANGE OCCURRED') (A); 

PUT SKIP DATA <I,J,K); 

/*SUBSCRIPT VALUES FOR TEST*/ 

END; 



ON SUBSCRIPTRANGE SYSTEM; 



END SORT; 



ACTION 
DURING 
COMPILATION i 



1. Remove the on-unit from the position it holds in the 
block and treat it as a separate begin block. 

2. Generate code to set a flag in the block enable cell of the 
DSA, to indicate that SUBSCRIPTRANGE is enabled 
throughout the block. 

3. Generate code to set up two on-cells in the DSA. Set up 
two corresponding ONCBs in the static internal control 
section (one for each ON-statement in the block). 

4. Place instructions equivalent to the ON-statements in 
compiled code. The first statement causes a code byte 
corresponding to SUBSCRIPTRANGE to be inserted in 
the first on-cell; the second statement causes the same 
code byte to be inserted in the second on-cell, and sets 
the first on-cell to zero. 

5. Generate code to insert flags in the ONCBs. Insert the 
address of the on-unit in the first ONCB. 

6. Generate code to carry out the on-unit. 

7. Generate code to check for the occurrence of SUB- 
SCRIPTRANGE in every statement that could potentially 
cause the condition to be raised. 



Figure 7.4. Example of error handling 




1 . The checking code generated by the compiler recognizes the occurrence 
of SUBSCRIPTRANGE and passes control to the error handler, after 
placing any required condition built-in function values in the ONCA. (In 
this case only the error code is generated.) 

2. The error handler checks to see if SUBSCRIPTRANGE is one of those 
conditions that can be enabled by the programmer. Since it is such a 
condition, a check is made, in the block enable cells of the DSA, to see 
if it is enabled. (If it were not enabled, control would return directly to 
to the point of interrupt.) 

3. Finding that the condition is enabled, the error handler then goes to 
the on-cells in the DSA. These are tested, using a translate-and-test table 
in the TCA, to see if SUBSCRIPTRANGE is established. After this, the 
action depends on whether the code for SUBSCRIPTRANGE is detected 
in the first or second on-cell, and consequently whether the first or 
second ONCB is used. 

4. If the first ONCB is used, on-unit action is indicated; if the second ONCB 
is used, standard system action must be taken. (Standard system action 
would also be taken if the code for SUBSCRIPTRANGE were not found 
in the DSA on-cells of the block in which the interrupt occurred, or in 
the DSA of any dynamically encompassing block.) 



On-unit action 

1. A further allocation of library workspace 
and a new ONCA are acquired in case they 
should be needed during execution of the 
on-unit. 

2. The on-unit (addressed from the ONCB) 
is executed. 

3. Provided there is not a GOTO out of the 
on-unit, return is made to the error 
handler. The error handler then carries 
out standard system action for return 
from an on-unit. 



System action 

For SUBSCRIPTRANGE, standard system 
action is to produce a message and raise 
ERROR. The message modules are called 
to put out a message dependent on the 
error code. 

ERROR is raised, and a search is made 
through all active blocks for an ERROR 
on-unit. Since there is none, standard 
system action is again taken; this is to 
raise FINISH. Since there is no FINISH on- 
unit, the standard system action of return- 
ing to IBMDPI R is taken, thus terminating 
the program. 



Unqualified, Conditions 



HARDWARE INTERRUPTS 



For unqualified conditions, the ON- 
statement action is merely to set a flag on 
in an on-cell which is associated with that 
statement. If there is more than one 0N- 
statement for the same condition in a 
block, the previous on-cells will be set to 
zero when second and subsequent on-cell 
flags are set on. The REVERT statement is 
executed by setting the flag in the latest 
on-cell to zero. The situation then 
reverts to that at the start of the block. 



The STXIT macro instruction, issued by 
IBMDPII during program initialization, 
specifies a save area and the address of a 
user exit routine to which control is to be 
passed after a program check interrupt. 
(All program check interrupts except 
"significance" and certain input/output are 
intercepted.) When a program check 
interrupt occurs, the supervisor saves the 
PSW and the contents of registers through 
15 at the time of interrupt in the special 
save area provided, and then passes control 
to the user exit routine. 



Qual ified Conditions 



On-cells are not generated for qualified 
conditions; instead, ONCBs are generated in 
the DSA of the block in which the 0N- 
statement appears. When the ON-statement 
is executed, one of the ONCBs is associated 
with the condition. The ONCB has the 
qualifier and the address of the associated 
on-unit placed in it, and the 'established* 
flag set on. If a further ON-statement for 
the same condition with the same gualifier 
has to be executed, the address of the on- 
unit is changed. For a REVERT statement, 
the establishment bit is set off. This 
returns the situation to that at the 
beginning of the block. 



IBMDERR-Error-Handling Module 



The error-handling module, IBMDERR, handles 
three situations. These are as follows: 

1. Hardware interrupts. 

2. PL/I conditions detected by the object 
program. 

3. Errors detected by the object program 
that are not directly related to PL/I 
conditions and which raise the ERROR 
condition. 

All three situations are ultimately 
dealt with as PL/I conditions. For 
example, the FIXEDOVERFLOW condition would 
be raised when fixed point overflow occurs 
and causes a program check interrupt. 
Where there is no directly-applicable, PL/I 
condition (for instance after a data 
interrupt) a system message is printed and 
the ERROR condition is raised. 



The "exit routine" consists of two 
fullwords of machine instructions, in the 
TCA appendage, immediately preceding the 
interrupt save area. These instructions 
set up addressability and ensure that 
register 1 is pointing at the interrupt 
save area before branching to entry point A 
of the error handler, IBMDERR. 

Before a program check interrupt can be 
handled by IBMDERR as a PL/I condition, 
action must be taken to prevent the system 
terminating the job should a further 
program check interrupt occur. The second 
word of the PSW (containing the interrupt 
address) is stored by IBMDERR in the 
register 14 slot of the save area which was 
current when the interrupt occurred. 
| Registers 0-12 are also saved in this 
|DSA. (Register 12 is saved in the field 
| normally used for register 15. Registers 
14 and 15 are saved later in IBMDERR»s 
DSA.) IBMDERR then changes the address in 
the PSW in the save area to an address in 
IBMDERR. An EXIT macro instruction is then 
issued to indicate to the supervisor that 
the program check exit is finished. 
Control then passes via the supervisor to 
the address in IBMDERR that has been 
inserted in the PSW. As an EXIT macro has 
been issued, handling of the interrupt 
appears to the supervisor to be finished. 
The address, in the field in the TCA, to 
which control will pass after a program 
check interrupt is then changed to 
IBMBERRC. Should an interrupt now occur 
during the execution of IBMDERR, control 
will pass to IBMBERRC, which terminates the 
job with a DUMP macro. IBMDERR can now 
| handle the interrupt. Having changed 
(register 12 to the PL/I register 12 as 
I previously saved, its first task is to 
generate a suitable error code that will 
equate the interrupt with a PL/I condition. 

The floating point registers are saved 
in IBMDERR 's DSA, if the interrupt is one 
corresponding to a PL/I condition, and 
control can then be passed to the main PL/I 
condition-handling routines described in 
the next section. There are, however, ^hree 
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special cases that require further action. 
These are: 

1. If the interrupt was floating point 
underflow, then the doubleword in 
which the floating point register 
which underflowed was stored is set to 
zero. 

2. If fixed point, exponent or decimal 
overflow, or fixed-point divide has 
occurred, then this may correspond to 
the PL/I condition SIZE and not to 
FIXEDOVERFLOW or ZERODIVIDE. If this 
is the case, a flag will have to be 
set in the program check interrupt 
qualifier in the TCA. A test of this 
flag is therefore made and the 
necessary action taken. 

3. If an operation exception occurs a 
branch is made to the operation 
interrupt analysis code in the program 
management area. A return code 
indicates whether the interrupt was 
caused by an attempt to execute a 
floating point instruction on a 
machine with no floating point 
hardware. The analysis code is set by 
IBMDPII as described in chapter 5. 



code is then generated, and the ERROR 
condition is raised. The situation is then 
treated as a PL/I condition. 

The second two bytes of the code passed 
when a PL/I condition has been raised 
indicate which on-unit built-in functions 
are relevant to the condition. If the 
condition is one that needs to be 
qualified, the qualifier is also passed. 

When a PL/I condition code is passed, 
action depends on whether the condition is 
one of those that can be enabled or 
disabled by the programmer. If it is such a 
condition, a test is made in the current 
enable cells of the DSA. If the condition 
is not disabled, then a search for a 
relevant established on-unit must be made. 
If the condition is disabled, a return is 
made to the point of interrupt. If the 
condition is not qualified, then a search 
is made through the on-cells of all active 
blocks to find a match for the number in 
the first byte of the code passed to 
IBMDERR. This is done with a translate- 
and-test instruction using the TRT table in 
the TCA. When found, the offset of the 
located on-cell gives the offset of the 
associated ONCB. A test can then be made 
to determine the action to be taken. 



SOFTWARE INTERRUPTS 



When the main condition-handling logic is 
reached, an error code will have been 
generated to indicate the type of error or 
condition that has been raised. For 
program check interrupts, the code is 
produced by the error module itself. For 
errors or conditions detected by the object 
program, the object program sets up this 
code. When the object program has detected 
the error, this will, in some cases, 
correspond to a PL/I condition. However, 
there are certain errors (such as 
attempting to take the square root of a 
real negative number) that do not have 
directly-related, PL/I conditions. For 
PL/I conditions, a four- byte code is 
passed. For other errors, the code consists 
of only two bytes. In the second case, the 
first byte indicates which class of error 
has occurred (I/O, computational, etc.). 
In the first case, the first byte is the 
identifier of the PL/I condition being 
raised (the same identifier is used in on- 
cells) . 

The error-handling module checks the 
first byte of the code to see whether it is 
handling an error or a PL/I condition* If 
the code indicates an error, then the 
message module IBMDESM is loaded into a VDA 
and called. This module prints the relevant 
diagnostic message; a suitable four-byte 



If the condition is one that needs 
qualification, a search for an active 
matching ONCB is carried out through the 
chain of dynamic ONCBs held in each DSA. 
If the dummy DSA is reached without a match 
being found, then standard system action is 
taken. This action is defined in IBMDERR. 
(The CHECK condition, which may be either 
qualified or unqualified, is handled 
differently, as described later in this 
chapter.) When a matching active ONCB is 
found, tests are then made, as follows, on 
the flags in the ONCB. 

Test 1. Is SNAP specified? If so, the 
message module IBMDESM is 
dynamically loaded and a SNAP 
message printed. 

Test 2. Is SYSTEM specified? (This can 
occur when "ON condition SYSTEM" 
has been specified.) If SYSTEM is 
specified, then the action for 
system action specified in IBMDERR 
is taken. 

Test 3. Does the on-unit consist only of a 
GOTO statement? If so, then the 
GOTO is executed without entering 
the on-unit. This saves the 
housekeeping involved in entering 
an on-unit. 

Test 4. Is the on-unit a null on-unit? If 
so, then the action on a normal 
return from the on-unit is taken. 
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If none of these tests is positive, then it 
is necessary to enter the on-unit. 



RETURN TO POINT OF INTERRUPT 



Before entering the on-unit, the 
following action must be taken. A new 
allocation of library workspace and ONCA 
must be initialized and its address put 
into the standard offset in the DSA of 
IBMDERR. This provides workspace for any 
further library modules that may be called. 
Tests must be made to see that the ONCA is 
correctly set-up for any built-in functions 
that may be used. The linkage to the error 
handler must also be altered to its 
original settings so that program check 
interrupts will cause entry to be made to 
the error handler by the entry point 
IBHBERRA rather than IBMBERRC. This 
ensures that the action specified by the 
PL/I program is^ taken if a program check 
interrupt occurs during the execution of an 
on-unit. 



Normal return from the on-unit to 
IBMDERR is made by a branch on register 14. 
Depending on the condition, a return to the 
interrupted program is then made, or some 
special action may be taken. Five PL/I 
conditions cause action other than return 
to be taken. 



If the condition was the ERROR 
condition, the FINISH condition is 
raised. 



2. If the FINISH condition was raised by 
a STOP statement or the raising of 
ERROR, or by the normal termination of 
the main procedure, then a return code 
is set in the correct field of the 
TCA, and GOTO performed to the 
initialization routine IBMDPIR* If 
FINISH was signaled, then return is 
made to the point of interrupt. 



3. If CONVERSION was raised, then a test 
is made in the ONCA, and if either 
ONSOURCE or ONCHAR has been accessed, 
control is passed to the address 
contained in the retry slot in the 
ONCA. The conversion is then 
attempted again. If the field has not 
been changed, then the ERROR condition 
is raised. 



If ENDPAGE was raised, then a return 
code is set in register 15 to indicate 
than an on-unit has been entered. 



5. If the condition was SUBSCRIPTRANGE, 
ERROR is raised. 



Software I nterrupt s 



If the condition was one that was detected 
by compiled code, then a return to the 
point of interrupt is made by a branch on 
register 14. 



Hardw are Interrupts 



For program check interrupts, the status of 
the program at the original point of 
interrupt has to be restored. This means 
that the contents of the system save area 
must be reset, so that they are identical 
with those saved after the original 
interrupt. (The PSW and the register 
values were saved in the interrupt DSA on 
entry to IBMDERR.) 

The method used is as follows. The 
address that is to be branched to, after a 
program check interrupt, is changed from 
IBMBERRC to another point in IBMDERR. An 
interrupt is then caused, and the 
supervisor gains control. Consequently, 
the address in IBMDERR is reached with the 
address of the system save area in register 
1. The contents of the save area and the 
PSW are then changed to those that were 
current after the original interrupt 
including the original value of register 
12. The point of entry for program check 
interrupts is then reset to IBMBERRA. An 
EXIT macro is then issued, and return is 
made to the address in the PSW, which is 
that of the instruction following original 
interrupt. 



The CHECK Condition 



The CHECK condition has to be handled in a 
different manner to other conditions. This 
is because it can be used as a qualified or 
unqualified condition and its enablement is 
under programmer control. 

The CHECK condition is disabled by 
default and is enabled by writing a CHECK 
prefix. It can be disabled for the duration 
of a statement or block by the NOCHECK 
prefix. Prefixes can take the form (CHECK) 
or (NOCHECK), or the form (CHECK ( A, B) ) or 
(NOCHECK (A, B) ) . When no name list is 
appended, the CHECK applies to all the 
relevant names in the program. An 0N- 
stateoent may also be written as either ON 
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CHECK or ON CHECK (A, B). ON-statements are 
independent of prefixes and may be included 
in a block to which no prefix applies. A 
qualified on-unit can be used with an 
unqualified prefix and vice-versa. 

Throuqhout this discussion, CHECK and 
NOCHECK without a name list are referred to 
as unq ualified. CHECK or NOCHECK with a 
name list are referred to as qualified. 



dyn am i c backchain for a relevant 
dynamic ONCB. 

3. If , there is no q u alified es t ablished 
on-unit, search for .an.u n qua lif ied 
establi shed on-unit . This involves a 
further search of the dy n amic 
backchain lookinq for appropriate on- 
cells. 

1 ' If no established pn-unit is found , 
take standard 



RAISING THE CHECK CONDITION 



This process is illustrated in figure 7.5. 



CHECK is normally raised by compiled code. 
This is done by inspecting the source 
proqram and qeneratinq calls to the error 
handler at appropriate points. As 
enablement is. statically descendant, it is 
possible to tell durinq compilation at 
which points CHECK is enabled and 
consequently at which points the calls to 
the error handler have to be made. For GET 
DATA statements, however, there is no way 
of predetermininq which items will be 
present in the input stream; when an item 
is input, therefore, the symbol table for 
that item is inspected to determine whether 
the CHECK condition may be enabled, and, if 
so, the error handler is called. 

With the exception of the CHECK 
condition, all conditions whose enablement 
is under proqrammer control are unqualified 
conditions. Consequently, their enablement 
or disablement can be indicated by one bit 
in the enable cells. This is because there 
are only two possibilities. Either the 
condition is enabled or it is disabled. 
With CHECK, however, there are many 
possiblities, because CHECK may be enabled 
for some variables and disabled for others. 
Consequently, the enable cells are used in 
a different manner for the qualified CHECK 
condition, and the enablement of qualified 
CHECK for any particular name is qiven in 
an ONCB. 

When the CHECK condition is raised, the 
error handler has to carry out the 
followinq tasks. 

1. T est to see if CHECK is enabled. This 
involves a search along the static 
backchain to determine, for each 
block, first if qualified CHECK is 
enabled or disabled for the particular 
name for which CHECK was raised, and 
then if unqualified CHECK is enabled 
or disabled. (This test is carried 
out only if it is not known at 
compile-time that the CHECK condition 
is enabled.) 

2. Search for a qualifi ed est a blished on - 
unit. This involves searchinq the 



TESTING FOR ENABLEMENT 



There are three bits that refer to CHECK in 
the enable cells; they have the followinq 
significance: 

Bit 

CHECK is enabled for certain items 

1 CHECK is disabled 

Bit 10 (only valid if bit 11 is set) 

The unqualified prefix that 
applies is NOCHECK 

1 The unqualified prefix that 
applies is CHECK 

Bit 11 

No unqualified prefix applies 

1 An unqualified prefix applies 

Bit is referred to as the "any-CHECK" 
enablement bit, and bits 10 and 11 as the 
"unqualified CHECK enablement bits." 
Enablement and disablement of qualified 
CHECK is indicated in the flaq bits of the 
ONCB. 

The test for enablement beqins by a test 
on the any-CHECK bit (bit 0) in the enable 
cell. If this is set to M'B, control is 
immediately returned to the caller. If the 
bit is set on, a search is made for a 
relevant qualified ONCB in the DSA of the 
block in which the interrupt occurred; if 
such an ONCB is found, the enablement 
status is determined from it. If no such 
ONCB is found, the unqualified CHECK 
enablement bits are tested for unqualified 
enablement or disablement. If bit 1 1 is 
on, the enablement status is taken from bit 
10. If bit 11 is not set, neither an 
unqualified CHECK nor an unqualified 
NOCHECK applies, and a further search must 
be made in the precedinq DSA on the static 
backchain. If the dummy DSA is reached 
without any of the tests provinq positive, 
CHECK is disabled. 
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Figure 7.5. Handling the CHECK condition 
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SEAECHING FOE ESTABLISHED ON-UNITS 



When it is known that CHECK is enabled, a 
search must be made for established on- 
units. This search is separate from the 
search for enablement. A return is first 
made to the DSA in which the interrupt 
occurred. 

Two searches are made, the first for a 
qualified on-unit. The complete dynamic 
backchain is searched for relevant ONCBs. 
If one is not found, a search is made 
through the backchain for enable cells that 
indicate unqualified CHECK. If nothing is 
found, standard system action is taken. 



Error Messages 



The library module IBMDESM is called by the 
error handler to generate the system 
messages and find the on-code value; 
control is then passed to IBMDESN to finish 
the system message, or to generate the SNAP 
message. In order to save space, IBMDESN 
is overlaid on IBMDESM. No new DSA is 
acquired for IBMDESN. 



'XXXXXXX' CONDITION RAISED [IN STATEMENT 
XXX] (AT/NEAR) OFFSET XXX IN PROCEDURE 
XXX 

and continues as for a SNAP SYSTEM message. 

The statement number is not always 
present in messages because the generation 
of execution-time statement numbers by the 
compiler is a compiler option. When 
statement numbers are generated, they are 
held on a block or procedure basis. For 
each block or procedure, a table in static 
storage relates each statement number to 
the, offsets of the corresponding 
instructions in compiled code. A field 
addressed by compiled code gives the 
address of the relevant table. 

The statement number is held in relation 
to its offset from the main entry point. 
Since the PL/I program need not have 
entered via this entry point, the offset is 
calculated independently from that given in 
the message. If the FLOW option is used, 
then additional information is printed out 
after every snap message. (See "The FLOW 
Option," later in this chapter.) 



Interrupts in Library Modules 



Message Formats 



System Messages: For non-PL/I conditions, 
system messages have the following form: 

IBMxxxx ' ONCODE'= xxxx message text 
[qualifier] IN STATEMENT XX AT/NEAE 
OFFSET xxx IN PROCEDURE WITH ENTRY xxxx 

The qualifier might, for example, consist 
of the file name. For PL/I conditions, the 
format of the message is much the same, but 
the name of the condition is also given. 
For example: 

IBM4821 »ONCODE'= 3108 • FIXEDOVERFLOW» 
CONDITION RAISED IN DECIMAL DIVIDE IN 
STATEMENT 31 AT OFFSET O0OA35 IN 
PROCEDURE WITH ENTRY ZERNES 

Snap .M essages : If an on-unit contains both 
SNAP and SYSTEM, the resulting message is 
essentially the system message followed by 
the line 

FROM (STATEMENT/OFFSET) xxx IN A (BEGIN 
BLOCK/PROCEDURE WITH ENTRY XXX/A 'xxxx' 
ON-UNIT) 

which is repeated as many times as 
necessary to trace back to the main 
procedure. If an on-unit contains only 
SNAP, the message begins 



When an interrupt occurs in a library 
module, the system message does not give 
the offset from the start of the library 
module, but gives the statement number of 
the statement in which the library module 
was called and the offset of this statement 
from the entry point of the procedure block 
in which it is contained. 



Identifying the Erroneous Statement 



If the interrupt was a software interrupt 
in compiled code, the address will be the 
return address that was used by the BALR 
instruction when IBMDERR was called. 

If the interrupt was a program check 
interrupt in compiled code, the address of 
the interrupt will have been moved from the 
old PSW and placed in the register 14 field 
by IBMDERR to simplify return to the point 
of interrupt. 

If the interrupt was in a library 
module, the address required is the point 
in compiled code at which the library 
routine was entered. This will have been 
placed in the register 14 field when the 
library module was called. 

Thus the address required to identify 
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the erroneous statement is always the 
address held in the register 14 field in 
the most recent compiled code DSA. 



F inding the Address of the Entr y Point 
of the Block 



The address of the entry point of the block 
is found by chaining back along the DSAs to 
the DSA before the last compiled code DSA. 
The start of the chain is the DSA addressed 
by the current value of register 13. The 
address of the reguired entry point is held 
in the save area of this DSA as the branch 
register contents (offset X'C*). The 
existence of the dummy DSA ensures that 
there will always be a DSA before the one 
in which the interrupt occurred. 

When the addresses of the entry point 
and the offending statement are known, the 
address of the block can be calculated and 
the statement number found* If the DSA in 
which the address of the link register was 
found is that of a procedure which was 
entered at its first entry point, then the 
offset already calculated will be the one 
reguired for the message. However, if the 
DSA containing the address of the interrupt 
was a begin block or on-unit, the offset 
for use on the statement number table is 
recalculated by using the exit address 
found above or taking from it the address 
of the main entry point, which is found in 
the statement number table. The offset is 
then calculated between the offending 
statement and the new address. This is 
necessary because the offsets given in the 
system message are taken from procedure 
entry points, whereas statement numbers are 
related to offsets in all blocks including 
begin blocks. 

For snap messages, once the first 
procedure has been found and the 
appropriate message generated, the rest of 
the trace gives information about both 
procedures and on-units, and thus their 
DSAs are treated in the same way. 



Ancill ary Information 



If the error was in I/O, then the address 
of the FCB of the file is passed to IBMDERR 
which stores it for IBMDESN to find the 
file name. Similarly, the address of the 
control section containing the condition 
name is passed to IBMDERR if the CONDITION 
condition is raised. 



Message Te xt Modules 



The message module IBMDESM calls on a 
number of message text modules to produce 
the relevant message. These modules 
consist essentially of the fixed message 
text portions of the message. The messages 
are held in groups. The groups are 
addressed from a table at the head of the 
module, and the messages in their turn are 
addressed by an offset from the start of 
each particular table in IBMDESM. The 
message required is determined from 
information in the error code. IBMDESN 
puts all error messages onto SYSPRINT 
provided that SYSPRINT has not been 
declared with unsuitable attributes. If it 
has been declared with unsuitable 
attributes, then the system messages go to 
the console operator, and the snap messages 
are ignored. 



Dump Routines 



A series of library modules are provided to 
implement the PLIDDMP facility. Module 
IBMDKDM is the dump bootstrap module which 
is part of the resident library. This loads 
and calls the transient dump control module 
IBMDKMR, which in turn loads and calls 
those modules reguired to carry out the 
dump options specified in the call to 
PLIDUMP. A number of transient modules are 
used to reduce the amount of storage 
required. The organization of these 
modules is shown in figure 7.6. 

In order to ensure that as much 
information as possible is provided when a 
call to PLIDDMP is made, a special STXIT 
macro instruction is issued to intercept 
program check interrupts. When a program 
check interrupt occurs, an attempt is made 
to continue. If the interrupt occurs in a 
program called from the dump control 
module, that particular routine is 
abandoned and a return is made to the dump 
control module. Any further routines needed 
to complete the information specified in 
the options are then called. If the 
interrupt occurs in the trace or file 
modules, a hexadecimal dump is produced. 
If the interrupt occurs during IBMDKDD, the 
hexadecimal dump module, the job is stopped 
with a DOS system dump macro to ensure that 
a hexadecimal dump will be produced. 

The dump control module IBMDKMR is 
divided into sections, and if an interrupt 
occurs in any of these sections, control is 
passed to a predefined address, at which 
point an attempt is made to continue with 
the next option. Processing then continues 
from that point. The dump modules are 
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Figure 7.6. Interrelationship of dump routines 



fully described in the publication DOS PL/I 
Transient Library Program Logic . 

I The dump control module acquires a VDA 
| of the correct size for each module that it 
I loads. When one module is completed it 
| overlays the next module, adjusting the 
| size of the VDA as necessary. Information 
J is transmitted to SYSLST by the PLIDOMP 
| transmitter IBMDKDT (this transmitter is 
| also used for COUNT information). SYSLST 
| must be assigned either to a printer or to 
ja tape device. 



Miscellaneous Error Routines 



These are: 

IBMDPEP Housekeeping error message 
module 

IBMDPES Insufficient non-LIFO storage 
message module 

Both routines are held in the transient 
library. 

IBMDPEP: This module issues an appropriate 
message in three circumstances: 

1. When there is no main procedure. 

2. When there is insufficient space for 
the program management area at 
initialization. 



Two further library routines are used in 
certain error situations. 



3. When there is an interrupt in the 
error handler. 
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The first message is written on SYSPRINT. 
The last two messages are both written on 
the console, because SYSPRINT may not be 
able to function in the situations that are 
handled. This could be either because of 
overwriting of control blocks, if there is 
an interrupt in the error handler, or 
because there is insufficient room, if 
there is no storage available. 

IBJJDPES: if no dynamic storage is 
available, this module puts out a message 
using either SYSPRINT or the console 
message transmitter module, if available. 
If neither can be used, the message is 
written on the console using an EXCP macro 
instruction. 



The FLOW and COUNT Options 



The FLOW and COUNT options are used to 
provide information about which statements 
are executed in a particular run of a 
program. The FLOW option is used to 
maintain a trace of the most recently 
executed statements. The COUNT option is 
used to maintain a count of the number of 
times each statement is executed. 

Both options are implemented by calling 
an interpretive library routine, IBMDEFL, 
at every point in a program where the flow 
of control may not be sequential. The 
library routine, IBMDEFL, analyzes the 
situation and updates tables to retain a 
record of the branches made. IBMDEFL is 
also called during program initialization 
to set up housekeeping information. Two 
transient library modules are used to 
interpret the tables set up by IBMDEFL and 
to put out the information. The routines 
are IBMDESN for the FLOW option, and 
IBMDEFC for the COUNT option. 

The compiler generates the same 
executable code for both the COUNT and the 
FLOW option. 

Points at which the flow of control may 
not be sequential are known as branch-in 
and branch-out points. For example, 
labeled statements and entry points are 
branch-in points, and GOTO statements are 
branch-out points. At branch-in and branch- 
out points the compiler places code that 
will call IBMDEFL. If the branches are 
taken, they are recorded. For COUNT they 
are recorded in a table known as the 
statement frequency c ount table. For FLOW, 
they are recorded in a table known as the 
flpJt statement table. 

Use of Branching Information for FLOW 

For the FLOW option, a list of the 



statement numbers at Which branches were 
taken and a list of any changes of 
procedure is retained. 



FLOW output consists simply of the list 
that is recorded by IBMDEFL and typically 
takes the form shown below. 

12 TO 18 

27 TO 35 IN SORTER 
76 TO 108 IN TESTER 
134 TO 77 IN SORTER 

This indicates that the program branched 
from statement 12 to statement 18, then ran 
sequentially from 18 to 27. After 
statement 27 it branched to, or called, 
statement 35 in the procedure called 
SORTER. Control then ran sequentially to 
statement number 76, at which point it 
passed to statement number 108 in the 
procedure called TESTER. Control then ran 
sequentially from 108 to 134 and finally 
passed to statement 77 in SORTER. 

Use of Branching Informati on for COUNT The 
COUNT option calculates the number of times 
each statement is executed by recording 
branch-in and branch-out points as they 
occur and analyzing them at the end of the 
program. 



The formula used for calculating the 
number of times each statement is executed 
from the branch count is: 

Cn=Cn- 1 +BIn-BOn- 1 



Where: 

Cn =the number of times the statement 

was executed. 
Cn-1 =the number of times the previous 

statement was executed. 
Bin =the number of times the statement 

was branched to. 
B0n-1=the number of times the previous 

statement was branched from. 

To retain the information, a count field 
is set up for every statement in the 
program, and branches-in and branches-out 
are recorded when they occur. Every time a 
branch-in is made, the count for the 
statement to which the branch is made is 
incremented by one. Every time a branch-out 
is made, the count for the statement after 
the branch-out is decremented by one. When 
the program ends, statements that have 
values other than zero mark the beginning 
and end of ranges of statements that have 
been executed the same number of times. 
The number of times the ranges of 
statements have been executed is calculated 
by adding the value in the count field to 
the sum of any preceding values. This 
process can be followed in figure 7.7. 
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PL/I PROCEDURE TO BE COUNTED 

1 COUNTIT:PROC OPTIONS (MAIN) ; 

2 DO 1=1 TO 2; 

3 PUT LIST (I) ; 

4 END; 

5 END COUNTIT; 

In this procedure, the do-loop in statements 2 through 4 will be 
executed twice, and the other statements once. Statement 2 will be executed 
three times as a return is made at the end of the loop to test the value 
of I. 



HISTORY OF THE ST ATEMENT FREQUENCY COUNT TABLE 

After the branch-in to statement number 1, the table is set up with a value 
of 1 for the first statement and for all others, thus: 

statement number 12 3 4 5 
branch count 10 

After the branch-out at statement 4, the count of the nex t statement 
is decremented by one and the table becomes: 

statement number 12 3 4 5 
branch count 10 0-1 

After the branch-in at statement 2, the branch count for statement 2 is 
incremented by one and the table becomes: 

statement number 12 3 4 5 
branch count 110 0-1 

At statement 4, a further branch out is made and a return made to 

statement 2 to test the value of I. One is subtracted from the value 

of statement five makin the count -2 and one added to the count 

of statement 2 making it 2. Because I is greater than 2 a 

branch is made after the test to statement 5. This results in 

one being subtracted from the count for statement 3 and one being added to 

the count for statement 5. At the end of the program the table reads: 

statement number 12 3 4 5 
branch count 1 2 -1 -1 



ANALYSIS OF THE STATEMENT FREQUENCY COUNT TABLE 

A value known as the current count , which is initially set to zero, 
is added to the branch count for each statement in turn. The sum is 
the number of times the statement was executed; this value also becomes 
the current count. 

statement number current count branch count times executed 

1 

2 1 

3 3 

4 2 

5 2 



Figure 7.7 How branch counts are used to calculate the number of times each 
statement is executed. 
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0+1= 1 
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1+2= 3 


-1 


3-1= 2 





2+0= 2 


-1 


2-1= 1 
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Special cases There are a number of special 
cases that require additional action, 
either by the compiler, or by IBMDEFL, or 
by both. These special cases arise for 
three reasons: 

1. Branches can be caused by 
interrupts, but the points at 
which they will occur cannot be 
predicted during compilation. 
Consequently the compiler cannot 
place calls to IBMDEFL at these 
points. 

2. Branches to labeled statements, 
can come from either the same 
block or a different block. 
Consequently the code generated by 
the compiler cannot be used to 
indicate whether a new block entry 
is required. 

3. The algorithm used for the COUNT 
option is not effective for CALL 
statements and function references 
because the branch-in and branch- 
out are made to and from the same 
statement. 

The first case is handled by IBMDEFL 
checking for the occurrence of an interrupt 
when it is called in situations where one 
could have occurred. The second case is 
handled by altering the GOTO code in the 
TCA so that it calls IBMDEFL to set 
appropriate flags when a GOTO out of block 
occurs. A test for the flags is made when 
the call to IBMDEFL for the branch-in at 
the labeled statement is made. The third 
case is predictable during compilation and 
is handled by the compiler setting up 
different code for branches-in to CALL 
statements and function references, and by 
IBMDEFL testing for such code. 



IMPLEMENTATION OF FLOW AND COUNT 



Tables Used by FLOW and COUNT 



To enable it to retain FLOW and COUNT 
information, IBMDEFL sets up tables in 
dynamic storage. 

Details of their formats are 
shown in appendix B. 

FL OW Option: FLOW information is retained 
in a table called the flow stat em ent table . 
The flow statement table has three 
sections; a header section containing 
housekeeping information, a statement 
number section holding the numbers of 
statements that were branched to or from 
plus flags to indicate the type of entry, 



and a procedure names section containing 
the names of procedures and on-units to 
which branches are made. The length of the 
flow statement table is determined by the 
values given to "n" and "m" when the FLOW 
option is specified. 

When all the spaces in the table for 
statement numbers or procedure names have 
been filled, the earliest entries are 
overwritten. The fields in the header 
section are used to indicate which is the 
next space available in the table. 

The table is set up during program 
initialization and is addressed from the 
TCA. 

COUNT Option: COUNT information is retained 
in tables called statement frequency count 
tables. The tables have a field for every 
statement. They are set up when an 
external procedure is entered. A table is 
needed for every external procedure because 
two external procedures can contain the 
same statement numbers. 

Statement frequency count tables are 
chained together and addressed from the TCA 
appendage (the TIA) . Two addresses are 
kept in the TIA, the address of the current 
statement frequency count table (that is 
the table that was last used) and the 
address of the statement frequency count 
table for the first procedure in the chain. 
Statement frequency count tables are 
associated with their matching external 
procedures by having the address of the 
static control section for the procedure 
placed at a fixed offset in the table. (A 
static control section is unique to an 
external procedure and its address can be 
easily accessed as it is addressed 
throughout compiled code by register 
three) . The last statement frequency count 
table in the chain has its chaining field 
set to zero. 

Interpreting the, Flo w Statement Table 



Information from the flow statement 
table is interpreted by the message module 
IBMDESN or the PLIDUMP routines, and 
transmitted in the form of statement number 
pairs which are associated with the names 
of procedures or with on-unit condition 
types. 

To extract the information, the message 
module must know from which points output 
in the statement number and procedure names 
section of the table output is to start. 
It must also be able to match the entries 
in the two sections of the table. 

The starting points in both sections of 
the table are found by checking whether the 
dummy entry, inserted during program 

* 
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initialization, has been overwritten. If 
the dummy entry has not been overwritten, 
the starting point is the first entry in 
that section of the table. If the dummy 
entry has been overwritten, the starting 
point will be the entry flagged as the next 
available entry. This is because the table 
is used cyclically, with the newest entry 
overwriting the oldest entry. 



Statement numbers are matched with 
procedure names by comparing the number of 
procedure names with the number of 
statement number entries that are flagged 
as being associated with procedure name 
entries. If the two numbers are the same, 
the first procedure name will be associated 
with the first statement number that 
reguires a procedure name. If there are 
more procedure names than statement numbers 
that reguire procedure names, the trace of 
procedures must be longer than the trace of 
statement numbers. Accordingly, the 
procedure names are put out without 
statement' numbers until the point is 
reached where the number of procedure names 
left is the same as the number of statement 
numbers that reguire them. From that point 
on statement numbers and procedure names 
are put out together. If there are more 
statement numbers that reguire procedure 
names than there are procedure names, the 
trace of statement numbers must be longer 
than the trace of procedure names. The 
earliest statement numbers are put out 
without names and, where a procedure name 
is reguired, "UNKNOWN" is used. When the 
number of names reguired matches the number 
available, the procedure names are put out 
with the statement numbers. 



Interpreting the statement frequency count 
tables 



Module IBMDEFC is called at program 
termination to print count information. 
Output is tabular and printed four columns 
to a page. An entire page is built before 
transmission. 

Output for a procedure begins with the 
procedure name. This is followed by the 
column headings: "FROM TO COUNT". The 
current count is initialized to zero and 
the first non-zero entry in the table is 
found. The associated statement number is 
then placed in the •FROM' part of a 
temporary line and the value for the non- 
zero entry is added to the current count. 
The entries for the following statements 
are scanned until one with a non-zero count 
value is found. The number of the 
preceding statement is then placed in the 
•TO' part of the line and the current count 
in the 'COUNT* part. This line is included 
in the page. The statement number found is 
then placed in the 'FROM 1 part of the 
temporary line and its branch count (which 
may be negative) is added to the current 
count. The scan of entries continues until 
another non-zero count is reached, and the 
process is repeated. 

If the count for a range is zero, the 
line is not moved into the page but the two 
statement numbers are saved for separate 
printing. Whenever a line is moved into 
the page, checks are made for the end of a 
column and the end of the page. When the 
page is full it is transmitted. 

The process is continued until the end of 
the table is reached. 

The next table is then processed, until all 
procedures have been handled. 

Finally, ranges of unexecuted statements 
are printed for each procedure. 
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Chapter 8: Record-Oriented Input/Output 



Note, on,. Terminology 



Discussions of record-oriented input/output 
tend to become confusing because of the 
wide use that is made of the word "file" 
throughout the Disk Operating System. In 
the DOS usage, the word "file" means a 
collection of data stored on an external 
storage medium. Throughout this chapter, 
however, the term "data set" is used for 
this concept. "File" is used in its PL/I 
sense - the representation (within a PL/I 
program) of a data set. 

Also used in this chapter are the terms 
record variable and key variable. These 
terms refer to the PL/I variables to which 
or from which data is moved. For example, 
in the statement: 



occurs, or when the end-of-file is reached, 
the LIOCS routines either set flags 
indicating the error or branch to error 
handling or end-of-file routines that can 
be specified by the programmer. 

The basic method used by the optimizing 
compiler to implement record I/O is to 
retain the source program information in a 
number of control blocks, and to pass these 
control blocks to PL/I library routines 
which interpret the information and carry 
out the necessary action by calling the 
data management LIOCS routines as reguired. 
The method is summarized below, and shown 
diagramatically in figure 8.1. Figure 8.16 
shows the overall scheme in greater detail. 



READ FILE (X) INTO (Y) KEY (Z) ; 

Y is the record variable, and Z is the key 
variable. The term transmission, statement 
is used to cover READ, WRITE, LOCATE, and 
REWRITE statements. These three terms are 
not standard PL/I terminology, but they are 
used for convenience throughout this 
chapter. 



Summary of Record I/O Implementation 



Introduction 



The DOS PL/I Optimizing Compiler uses the 
logical input/output control system (LIOCS) 
routines of DOS data management to 
implement record I/O. These routines offer 
facilities similar to, but not the same as, 
those of the PL/I language. 

The LIOCS routines reguire that: 

1. A define-the-file control block (DTF) 
is set up to describe and identify the 
data set. 

2. OPEN and CLOSE macro instructions are 
issued to open and close the data set. 

3. GET, PUT, READ, or WRITE macro 
instructions are issued to store or 
obtain a new record. 

The LIOCS routines transmit the data one 
block at a time between the data management 
buffer and the external medium, but each 
separate macro instruction issued by the 
program results in only a single record 
being passed. When a transmission error 



Compilation 



During compilation the compiler sets up a 
number of control -blocks that describe the 
file declaration/ and the OPEN, CLOSE, and 
transmission^statements. The compiler also 
generates code to complete these control 
blocks from execution-time information, and 
to pass their addresses to the PL/I library 
or LIOCS routines. 

The compiler also determines which LIOCS 
routine will be used for each transmission 
statement, and generates an ESD record so 
that the appropriate routine will be link- 
edited. 

If no environment options depend on 
execution time values, the compiler also 
acguires buffers, and completes the DTF and 
FCB. This reduces the work to be done 
during execution to little more than 
issuing the OPEN macro instruction. The 
process is referred to as optimization of 
the OPEN function in the compiler 
diagnostic messages. 
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Set up control blocks 
from file declaration 
and I/O statements 



COMPILER 



Call PL/I library 
or LIOCS routines 
passing control blocks 



COMPILED CODE 



OPEN & CLOSE STATEMENTS TRANSMISSION STATEMENTS 



In-line I/O Library call I/O 



PL/I LIBRARIES 



J 



OPEN/CLOSE BOOTSTRAP 
ROUTINE 

(Resident library) 



TRANSMITTER INTERFACE 
ROUTINE 

(Resident library) 



OPEN ROUTINES 



(Transient library) 



CLOSE ROUTINE 



(Transient library) 



PL/I TRANSMITTER 



(Transient library) 



LIOCS OPEN 
ROUTINE 



LIOCS CLOSE 
ROUTINE 



^ 



I DATA MANAGEMENT 
I (LIOCS) ROUTINES 



S 



LIOCS TRANSMITTER ROUTINE 



Figure 8.1. The principles used in handling record I/O statements 
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File type: Consecutive buffered 



Record type: F,FB 



Statement 
READ SET 
READ INTO 



WRITE FROM 
(fixed string) 

WRITE FROM 
(varying string) 

WRITE FROM 
Area * 

LOCATE A 



| Record variable restrictions 

None 

Length known at compile time 

(max. length if a varying string) 

Length known at compile time 



| ENVIRONMENT option reguirements 
None 
RECSIZE known at compile time 

RECSIZE known at compile time 

RECSIZE known at compile time 
SCALARVARYING option used 

RECSIZE known at compile time 
RECSIZE known at compile time 



Maximum length known at compile 
time 



Record type: U 



READ SET 
READ INTO 



WRITE FROM 
(fixed string) 

WRITE FROM 
(varying string) 

WRITE FROM 
(area *) 

LOCATE 



None 

Maximum length known at compile 
time 

Length known at compile time 



Not BACKWARDS 

BLKSIZE known at compile time 

BLKSIZE known at compile time 



BLKSIZE known at compile time 
SCALARVARYING option used 

BLKSIZE known at compile time 



BLKSIZE known at compile time 



Notes: All statements must be found to be valid during compilation. File parameters 
or file variables are never handled by in-line code. 



* Including structures whose last element is an unsubscripted area. 



Figure 8.2. Conditions under which I/O statements are handled in-line 
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Data Set 
Organization 


File Attributes 


Access 
Methods 


CONSECUTIVE 


SEQUENTIAL 


INPUT 

OUTPUT 

UPDATE 


BUFFERED 

or 

UNBUFFERED 


SAM 


INDEXED 


SEQUENTIAL 


INPUT 

OUTPUT 

UPDATE 


BUFFERED 
UNBUFFERED 
is ignored 


ISAM 


DIRECT 


INPUT 
UPDATE 




ISAM 


REGIONAL 


SEQUENTIAL 


INPUT 

OUTPUT 

UPDATE 


BUFFERED 

or 

UNBUFFERED 


DAM 




DIRECT 


INPUT 

OUTPUT 

UPDATE 


DAM 


VSAM 
entry-sequenced 


SEQUENTIAL 


INPUT 

OUTPUT 

UPDATE 


BUFFERED 

or 

UNBUFFERED 


VSAM 


VSAM 
key-sequenced 


SEQUENTIAL 


INPUT 

OUTPUT 

UPDATE 


BUFFERED 

or 

UNBUFFERED 


VSAM 


DIRECT 


INPUT 
UPDATE 


BUFFERED 

or 

UNBUFFERED 


VSAM 



i ; . j 



Figure 8.3. Data management access methods for record-oriented transmission 



Execution 

PL/I record I/O statements are executed in 
the following manner: 

OPEN - by a call to the open routines in 
the PL/I library. 

CLOSE - by a call to the close routines in 
the PL/I library. 

READ. WRITE. LOCATE. REWRITE - generally by 
a call to the PL/I library transmitter 
modules via an interface routine, IBMDRIO. 
The transmitters call the data management 
(LIOCS) routines. (This process is 
referred to "library-call I/O.") 



On buffered consecutive files, most 
transmission statements are 
executed by a direct call from 
compiled code to the data 
management (LIOCS) routines. (This 
process is referred to as "in-line 
I/O.") Figure 8.2 shows the 
conditions under which I/O 
statements are handled in-line. 

Implicit open - by manipulation of 
addresses"~so that all attempts to access 
the file when it is not open result in 
control being passed to the open routines 
in the PL/I libraries. 

Implicit close - by the program 
termination routine checking for open 
files, and calling the PL/I library routine 
to close them. 
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File Type 



| Device Type 



DTF Type 



SEQUENTIAL BUFFERED CONSECUTIVE 


| Card 


| DTFCD 






| Printer 


| DTFPR 






| Tape 


| DTFMT 






j Disk 


| DTFSD 






| logical unit = SYSIPT, 


| DTFDI 






| SYSLST, SYSPCH 








| (F format only) 






SEQUENTIAL UNBUFFERED CONSECUTIVE 


| Tape 


| DTFMT 


(work) 




| Disk 


| DTFSD 


(work) 


INDEXED 


I Disk 


| DTFIS 




REGIONAL (1) AND (3) 


| Disk 


| DTFDA 





Note: DTFs are not set up for VSAM files 



L J 



Figure 8.4. Type of DTF set up for different PL/I file types 



Access Meth od and DTF Type 



The access method used for different PL/I 
file types is shown in figure 8.3. The DTF 
used for different file types is shown in 
figure 8.4. 



Compiler Output for Record I/O 



The output of the compiler for record I/O 
is subdivided below according to the 
statement type in the source program. 
Figure 8.5 shows the control blocks 
generated for each statement type, and the 
relationship between these control blocks. 



File Declaration 



| For every file declaration, except those 
with ENV (VSAM) , a def ine-the-file control 
block (DTF) , a file control block (FCB) , an 
environment control block (ENVB) , and a 
field to contain the filename and the 
length of the filename are set up. All 
these items are held in static internal 
storage for INTERNAL files, and in a 
separate control section for external 
files. 

I For a file declared with ENV (VSAM) a DTF 
fis not set up. Instead an ACB (access 



method control block) is used which is 
generated by the library routines during 

| execution. The FCB, ENVB and filename 
fields are set up as for other files. If a 
file that is declared with ENV (INDEXED) is 

| used to access a VSAM key sequenced data 
set, the VSAM interface is used. 

The DTF is required by DOS data 
manaqement. There are nine types of DTF 
that can be used by the compiler. The type 
used depends on the file and device type, 
as shown in fiqure 8.4. Full details of 
the DTF are qiven in the publication DOS 
Sup erv isor and Input/Outpu t Macr o 
Instructions. 

Where there are no environment options 
that depend on execution time values the 
compiler also acquires buffers and fills in 
the DTF fields with buffer addresses. The 
buffers are held within the file control 
section for external files and within the 
static internal control section for 
internal files. The compiler also does any 
necessary checking on items such as 
blocksize. If the declaration is invalid 
the compiler generates a message and makes 
no attempt to optimize the operation. 

When the operation is optimized a flag 
is set in the FCB. 

T he FCB is a control block that is used 
as a central addressing area for file 
information. It holds the addresses of the 
| DTF, and the ENVB, the filename and 
filename length. For VSAM files the 
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I address of the ACB (access method control 
| block) is set when the file is opened and 
jthe block has been generated. It also 
holds a mask indicating which statements 
are valid for the file. The format of the 
FCB is shown in appendix B. 



Both the FCB and DTF are 
complete as possible during 
those values which are not a 
execution time are added to 
during the execution of the 
These yalues are derived fro 
the open control block OCB ( 



made as near 
compilation; 
vailable until 
the blocks 
open routines. 
m the ENVB and 
see below) . 



The ENVB contains the addresses of such 
items in the environment options as can be 
declared with variable values. The format 
of the 1 ENVB is given in appendix B. 

The filename and filena me lengt h are used 
by the error message modules when the name 
of the file is needed for an error message. 



The OPEN Statement 



For an OPEN statement, the compiler 
generates a call to the library open/close 
bootstrap routine, IBMDOCL; if the 
attribute input or output has been used in 
the OPEN statement, the compiler also 

generates an open control blo ck (OCB)„. The 

OCB indicates whether the input or the 
output attribute was used in the statement. 
The OCB is held in static internal storage 

For each file to be opened, the following 
information is passed to the open/close 
bootstrap routine: 

1. The address of the FCB. 

2. The address of the OCB (or zero, if no 
OCB exists) . 

3. The address of the TITLE, if 
specified. 



Transmission Statements 



The code and control blocks generated for a 
transmission statement depend on whether it 
will be handled by an in-line call to the 
LIOCS routines or by a call to the PL/I 
library transmitter. 

In-line record I/O statements : the 
compiler generates a call to an LIOCS 
routine, which uses information in the DTF 
as a parameter list. Compiled code 
addresses the LIOCS routine through a field 
in the DTF. The DTF is addressed from a 



field in the FCB. 

For an in-line call, code may also be 
generated either to move the data to the 
record variable or to set a pointer to the 
data, and to check whether the transmission 
has been successful* 

The code and control blocks generated 
for an in-line record I/O statement are 
shown in figure 8.6. 

Library-call rec or d I/O statements : the 
compiler generates a call to the PL/I 
transmitter module, IBMDBIO. IBMDBIO has 
the following parameter list passed to it: 

Address of FCB 

Address of reguest control block 

(ECB) 
Address of record descriptor (ED) ) ; 

or , address ignore factor; or, 

address at which to set pointer 
Address of key descriptor (KD) ; or 

zero if no key descriptor 
Address of event variable (EV) ; or , 

zero if no event variable 
Abnormal locate return address 

(locate statements only) 

The FCB is generated from the file 
declaration and is described above. The 
remainder of the control blocks in each 
parameter list are generated for the 
transmission statement. 

The reguest control block (RCB ) defines 
the statement type. It consists of two 
words. The first word is a fullword of 
flags that define the statement. types, 
indicating whether the statement is READ 
SET, READ INTO, WRITE FROM, etc. The 
second word is a machine language 
instruction that will be executed by 
IBMDRIO. (For exact format, see appendix 
B.) The RCB is set up in static internal 
storage. 

A branch instruction is placed in the 
second word of the RCB if, during 
compilation, the statement type can be 
validated. A direct branch to the 
transmitter will then occur during 
execution. If, however, the statement type 
cannot be checked during compilation, or if 
it is invalid, a test-under-mask 
instruction is placed in the RCB. The 
check of statement validity will then be 
made during execution, using the flags in 
the FCB which indicate the valid statements 
for the file. 

All transmission statements can be 
checked for validity during compilation 
except for statements on unbuffered 
consecutive files, file parameters, and 
file variables. Unbuffered consecutive 
files can be opened for either INPUT or 
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CONTROL BLOCKS GENERATED FROM 
FILE DECLARATION 



CONTROL BLOCK GENERATED FROM 
OPEN STATEMENT 



CONTROL BLOCKS GENERATED FROM 
INPUT/OUTPUT STATEMENTS 



CONTROL BLOCKS GENERATED FOR 
VSAM FILES 



File control block (FCB) 



Function: Acts as a central source of 
information about the file 
Location: In static storage 
When Generated: During compilation 
Contents include: 

Flags indicating 

valid statements 

Transmitter name 

Transmitter address 

Error module address 

ENVB address 

DTF address- — 



Filename address 

Buffer address 

Flags and workspace for 

the transmitters 

ACB address 



Environment control block (ENVB) 



Function: Holds information on 

environment options (except the 

MEDIUM option) 

Location: In static storage 

When generated: During compilation 

Contents: Addresses of 

blocksize 

record length 

of buffer tracks 

KEYLOC value 

key length 

indexarea size 

addbuf 



Define the file control block (DTF) 



Open control block (OCB) 



Function: To hold information 
necessary to data management 
Location: In static storage 
When generated: As far as 
possible during compilation, and 
completed during open from 
information in the ENVB and FCB 
Contents: See data management 
documentation 



Function: To contain file attributes 

given in OPEN statement 

Location: In static storage 

When generated: During compilation 

Contents: The attribute INPUT or 

OUTPUT when specified on the OPEN 

statement. 



Filename 



Function: To hold information 

about the filename 

Location: In static storage 

When generated: During compilation 

Contents: Filename and its length 



Request control block (RCB) 



Access Method control block , (ACB) 



Function: Holds a definition of the statement 

for execution-time checking 

Location: In static storage 

When generated: During compilation, for 

library data management calls only 

Contents: Flags defining statement 

Code for TM instruction, or 
a branch instruction (if 
checking was done during 
execution) 



Function: To hold information required by 
data management for VSAM files. 
Location: Non- L I FO storage 
When generated: Durinq the execution of OPEN 
Contents: See data management document- 
ation. 



Input Output control block (OCB) 



Record descriptor (RD) 



Function: To describe the record variable 

Location: Depends on storage class of record 

variable 

When generated: Depends on storage 

class of record variable 

Contents: Length and address of record 

variable 



Function: To hold address information for 

VSAM files. 

Location: Non-LIFO storage 

When generated: During the execution of OPEN 

Contents: Equivalent of FCB for VSAM files. 



Key descriptor (KD) 



Function: To describe the key variable 

Location: Depends on storage class of key 

variable 

When generated: Depends on storage 

class of key variable 

Contents: Length and address of key 

variable 



Figure 8.5. Control blocks used in record I/O 
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SOURCE LISTING 



STMT 



1 EXAMPLE: PROC OPTIONS (MAIN) ; 

2 DCL LINE FILE RECORD INPUT 

ENV(FB,RECSIZE(80),BLKSIZE(400),MEDIUM(SYSIPT,2540)), 

CARD CHAR (80) ; 

3 READ FILE (LINE) INTO (CARD) ; 

4 END; 



000000 00000008 

000004 0000005E 

000008 0000005E 

00000C 00000000 

000010 00000000 

000014 00000000 

000018 00000000 

00001C 00000000 

000020 91E091E0 

000024 00000000 

000028 000000940000005E 



STATIC INTERNAL STORAGE MAP 

PROGRAM ADCON 

PROGRAM ADCON 

PROGRAM ADCON 

A. . IBMBOCLA 

A. .IBMBOCLC 

A. . IBMBRIOA 

A. .IBMBRIOD 

A. .STATIC 

CONSTANT 

A. .FCB 

COMPILER LABEL CL.3 



000000 



000090 



0000B0 
0000B8 
0000BC 

0000C8 
0000CC 
0000D0 
0000D4 



9100000000000000 
0000000000000000 
0000008800000090 

oooooocooooooooo 

D8E9000002110100 
8880202002000000 
0190000000000050 
000000F8000000F8 
00000000001COOOO 
00000000000000F8 
0000028800000000 
0000000000000000 

oooooooocooooooo 

0000000000000000 

0000000000000000 

0000000000000000 

0004D3C9D5C50000 

C0000000010000BO 

010000B4020000B8 

020000B8020000B8 

020000B8020000B8 

0000800000000001 

0OOO0OEO 

0000000000000000 

02050202 

00000288 

00000000 

020000F8 

2000019041BE0000 

470000000000 



STATIC EXTERNAL CSECTS 



FCB 



ENVB 



DTF (CONSTANT PART) 

DTF (VARIABLE PART) 

DTF (CONSTANT PART) 

DTF (VARIABLE PART) 

DTF (CONSTANT PART) 

DTF (VARIABLE PART) 

DTF (CONSTANT PART) 



OBJECT LISTING 



* STATEMENT NUMBER 



000062 


18 


72 






000064 


58 


90 


3 


024 


000068 


18 


29 






00006A 


58 


10 


2 


018 


00006E 


58 


80 


2 


05C 


000072 


58 


B0 


8 


000 


000076 


5A 


B0 


8 


004 


00007A 


50 


B0 


8 


000 


00007E 


59 


B0 


8 


008 


000082 


47 


DO 


7 


030 


000086 


41 


80 


3 


028 


00008A 


58 


FO 


1 


010 


00008E 


45 


EO 


F 


008 


000092 










000092 


D2 


4F 


D 


0A8 B 000 


000098 










000098 


91 


80 


2 


02C 


00009C 


47 


EO 


7 


044 


0000A0 


58 


FO 


3 


018 


0000A4 


05 


EF 






0000A6 










0000A6 


18 


27 







CL.2 



CL.3 



CL.4 



LR 


7,2 


L 


9,36(0,3) 


LR 


2,9 


L 


1,24(0,2) 


L 


8,92(0,2) 


L 


11,0(0,8) 


A 


11,4(0,8) 


ST 


11,0(0,8) 


C 


11,8(0,8) 


BNH 


CL.2 


LA 


8,40(0,3) 


L 


15,16(0,1) 


BAL 


14,8(0,15) 


EQU 


* 


MVC 


CARD (80), 0(11) 


EQU 


* 


TM 


44(2),X*80' 


BNO 


CL.4 


L 


15, A.. IBMBRIOD 


BALR 


14,15 


EQU 


* 


LR 


2,7 



Set R2 as program base 

Place address of FCB in R9 

Place address of FCB in R2 

Place address of DTF in Rl 

Pick up deblocking words in DTF 

Place previous record address in Rll 

Add record length to old address 

Store in current record address 

Test if current record address is in buffer 

If it is branch around LIOCS call 

Pick up end-of-file address from static storage 

Call LIOCS routine to get new buffer 

Move record into record variable (CARD) 

Test for errors 
Branch if no errors 

If errors call record I/O bootstrap routine 
Restore R2 as program base 



Figure 8.6, Annotated list showing* record I/O statements handled by in-line code 
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SOURCE LISTING 



STMT 



EXAMPLE:PROC OPTIONS^IIJINI.^^ ^^ INpuT RECDR0 

ENV(F,RECSIZE(8O).MEDIUM(SYSO01,2311)), 
CARO CHAR (80); 
READ FILE J LINE) INTO (CARD); 



END; 

* PROLOGUE BASE 
00005E 02 07 



000064 
000068 
00006 C 



41 60 
50 60 
05 20 



0A8 
OBO 
0A8 



3 028 



* PROCEDURE BASE 



MVC 16818,13), 40*3) 

LA 6, CARO 

ST 6,168(0,13) 

BALR 2,0 



move skeleton record descriptor to DSA 
complete descriptor with address 
of record variable 
set R2 as program base 



* STATEMENT NUMBER 3 



00006E 
000072 
000076 
00007A 
00007E 



41 90 D 0A8 
50 90 3 040 
41 10 3 038 
58 FO 3 014 
05 EF 



LA 9,168(0,13) 

ST 9,64(0,3) 

LA 1,56(0,3) 

L 15,A..IBMBRI0A 

BALR 14,15 



pick up address of record descriptor 
place in argument list 
point Rl at argument list 
branch and link to IBMDRIO 



STATIC INTERNAL STORAGE MAP 



000000 


00000008 


PROGRAM ADCON 


000004 


0000005E 


PROGRAM ADCON 


000008 


0000006E 


PROGRAM ADCON 


oooooc 


OOOOOOOO 


A..IBMBOCLA 


000010 


OOOOOOOO 


A. . IBMBOCLC 


000014 


OOOOOOOO 


A..IBMBRIOA 


000018 


OOOOOOOO 


A..IBMBPGQA 


0000 1C 


OOOOOOOO 


A.. STATIC 


000020 


O08000O007FF00O0 


CONSTANT request control block 


000028 


0000000000000050 


RECORD DESCRIPTOR 


000030 


91E091E0 


CONSTANT 


000034 


OOOOOOOO 


A. .FCB 


0000 38 


OOOOOOOO 


A..FCB 


00003C 


00000020 


A.. CONSTANT 


000040 


OOOOOOOO 


A. .RO 


000044 


OOOOOOOO 


A.. NULL ARGUMENT 


000048 


OOOOOOOO 


A.. NULL ARGUMENT 


00004C 


80000000 


A.. NULL ARGUMENT 



STATIC EXTERNAL CSECTS 



000000 1188000000000000 
0000000000000000 
0000008800000090 
OOOOOOB800000000 
C3E9000002110200 
8080000002000000 
0000000000000000 
OOOCOOOOOOOOOOOO 
0000000000000000 
OOOCOOOOOOOOOOOO 
0000000000000000 

ooooooooooooocoo 

0000000000000000 

ooooocoooooooooo 

0000000000000000 

ooooooooooooocoo 

0004D3C9D5C50000 

00C090 40000000020000B0 

010000B4020000B0 

02000080020000 BO 





02O0OOB0O20000BO 








OOOOBO 


0000920400000101 


DTF 


(CONSTANT 


PARTI 


0000B8 


00000100 


DTF 


(VARIABLE 


PART) 


OOOOBC 


0000000000000000 
2060D3C9D5C54040 
40000 E2900000000 
0000000900640000 
OOOCOOOOOOOOOOOO 
OOOOOOOOOOOOFFOO 
000000642000CCA4 
AOOOCCAC 


DTF 


(CONSTANT 


PART) 


000OF8 


070000EE 


DTF 


(VARIABLE 


PART) 


OOOOFC 


40000006 


DTF 


(CONSTANT 


PART) 


000100 


310000F0 


DTF 


(VARIABLE 


PARTI 


000104 


40000005 


DTF 


(CONSTANT 


PARTI 


000108 


08000108 


DTF 


(VARIABLE 


PART) 


00010C 


000000000 30CD278 
200000010500D280 
2000000 1 


DTF 


(CONSTANT 


PARTI 


000120 


310000FO 


DTF 


(VARIABLE 


PARTI 


000124 


40000005 


DTF 


(CONSTANT 


PARTI 


000128 


08000128 


DTF 


(VARIABLE 


PARTI 


000 12C 


COGCOOOO 


OTF 


(CONSTANT 


PART) 


000130 


1E000148 


DTF 


(VARIABLE 


PART) 


000134 


30000008 


DTF 


(CONSTANT 


PARTI 


000136 


12000148 


DTF 


(VARIABLE 


PARTI 


000 13C 


0000000800000000 
01000000 


DTF 


(CONSTANT 


PARTI 



Figure 8.7. Annotated object program showing record I/O statements handled by 
library subroutines 
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OUTPUT in the OPEN statement and, 
consequently, the statement validity cannot 
be determined until the file is opened. 
With file parameters and file variables, it 
is impossible to know which file will be 
referred to, and consequently the validity 
of statements usinq file parameters or file 
variables cannot be determined durinq 
compilation. 

The format of the RCB is qiven in 
appendix B. 

The record descriptor (ED) contains the 
address, lenqth and type of the record 
variable. It is qenerated only if a record 
variable is required. (For exact format, 
see appendix B. ) 



The key descriptor (KD) contains the 
address and lenqth of the key variable, 
is qenerated only if a key variable is 
used. (For exact format, see appendix B.) 



If the record variable or the key 
variable is STATIC INTERNAL, a complete RD 
or KD is set up and placed in static 
internal storaqe durinq compilation. In 
most other circumstances, a skeleton RD or 
KD will be set up which will- be completed 
durinq execution by the inclusion of the 
address. The completed descriptor may be 
moved into temporary storaqe. In certain 
conditions, no skeleton is produced: the 
complete descriptor is built in temporary 
storaqe by compiled code. 

The event variable (EV) contains 
information about the event that has been 
associated with the event I/O statement. 
(For exact format, see appendix B.) The 
implementation of event I/O is covered 
briefly at the end of this chapter, and 
more fully in chapter 11 under the headinq 
"The WAIT Statement." 

The abnormal- locate return address is 
used only for LOCATE statements. It is the 
address to which control will be passed if 
an error is detected in a locate statement 
and a normal return is made after execution 
of the on-unit. The abnormal-locate return. 
address is usually the start of the next 
statement. 

The code and control blocks qenerated 
for a transmission statement usinq a 
library call to the LIOCS routines are 
shown in fiqure 8.7. 



CLOSE Statements 



For CLOSE statements, the compiler 
qenerates a call to the open/close 
bootstrap routine, IBMDOCL, passinq to it 



the address of the FCB, and, if required, 
flaqs indicatinq the presence of the LEAVE 
or UNLOAD option. 



Library Routines in Record I/O 



Because the amount of code involved in 
implementinq a record I/O statement is 
quite larqe and would be duplicated for 
each similar record I/O statement, record 
I/O is handled mainly by PL/I library 
routines. The work done by library routines 
is summarized in fiqure 8.12. 



It Type_of Library Modules Used 



The library modules used by the compiler 
can conveniently be considered under three 
headinqs: 



1 . Open and close 



ules - called to 



open and close the files. 

2. Trans mi tter, .m odules - called to 

transmit data by callinq the LIOCS 
routines. The PL/I transmitters hold 
the error and end-of-file routines for 
both library and in-line LIOCS calls. 

For consecutive buffered files, the 
error and end-of-file routines are 
provided as a separate library module, 
IBMDRRR. This module is loaded when 
the file is opened, and can be 
considered as part of the transmitter. 

3- Error routines - used, when PL/I 
conditions occur, to handle 
housekeepinq problems and calls to the 
error handler, IBMDERR. 

The routines involved are shown in 
fiqures 8.8, 8.9, and 8.10 
respectively. Their interrelationship 
is shown in fiqure 8.11. 

Because of their lenqth, the major 
modules are held in the transient library, 
and are loaded and called when required by 
small resident modules. 

The open and close routines are loaded 
by the open/close bootstrap routine, 
IBMDOCL. Transmitters are loaded by the 
transient open routines, and are called via 
the resident transmitter interface module, 
IBMDRIO. The error routines are loaded by 
j bootstrap entry points in IBMDOCN. The 
| module IBMDOCN contains the open/close 
| parameter list and is seperated from 
| IBMDOCL to improve overlonq performance. 
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r 

1 Resident 


library bootstrap routine IBMDOCL - loads and calls appropriate transient 


t module 








| Entry point | 


Function 




| IBMBOCLA 


1 


Explicit open 




1 IBMBOCLB 


1 


Implicit open for library-call I/O 


| IBMBOCLC 


1 


Explicit close 




| IBMBOCLD 


1 


Implicit close 




\ IBMBOCLG 


1 


Implicit open for in-line I/O 




| Transient 


library open and close modules 




| Name 


1 


Function 




| IBMDOPM 




Open stage 1 consecutive unbuffered files 


| IBMDOPP 




Open stage 1 consecutive buffered 


files 


| IBMDOPS 




Open stage 1 stream files 




| IBMDOPX 




Open stage 1 regional and indexed 


files 


| IBMDOPO 




Open stage 2 consecutive buffered 
DTF except for disk and tape 


files acquire buffers initialize 


\ IBMDOPT 




Open stage 2 stream files acquire 
disk and tape 


buffers initialize DTF except for 


| IBMDOPY 




Open stage 2 regional and indexed 
initialize DTFDA 


files acquire buffers and 


| IBMDOPU 




Open stage 3 consecutive buffered 
disk or tape 


and stream files initialize DTF for 


\ IBMDOPZ 




Open stage 3 regional and indexed 
initialize DFTIS 


files acquire buffers and 


| IBMDOPV 




Open for VSAM files 




| IBMDOCA 




Close files 




| IBMDOCV 




Close for VSAM files 





l_ .. . _ 1 

Figure 8.8. PL/I resident and transient library OPEN and CLOSE routines 

transmitter. 



Openin g a File Expli citly 



For an explicit open, a call is made to the 
resident library module IBMDOCL to open the 
file. This routine, known as the 
open/close bootstrap, is called once for 
every file that requires opening and is 
passed the address of the FCB, the address 
of the OCB, if one is reguired, and the 
address if the string locator for the title 
option, if the TITLE option is being used. 
IBMDOCL then calls one of five transient 
open modules depending on the file type. 

For VSAM files the compiler places the 
address of IBMDOPV in the FCB and 
consequently IBMDOPV is called by IBMDOCL. 
IBMDOPV acquires space for an ACB (access 
control block) , IOCB (input/output control 
block) and an RPL (request parameter list) 
and then creates an ACB using a 6ENCB macro 
instruction. IBMDOPV also sets fields in 
the FCB so that the correct error module 
will be called, and loads the appropriate 



For files other than VSAM there are four 
groups of modules, one group for 
consecutive buffered files, one group for 
stream files, one group for regional and 
indexed files and a single module for 
consecutive buffered files. The module 
called by IBMDOCL is the major module in 
the group. It has the job of issuing the 
open macro instruction, loading the 
transmitter if necessary, setting up the 
ERROPT and EOFADDR fields in the FCB and 
handling TITLE, PAGESIZE and any 
repositioning options such as REWIND. If 
the buffer space has been allocated during 
compilation no further action will be 
necessary. However, if buffers are 
reguired and the DYNBUFF option, variable 
environment options, or an invalid 
declaration has prevented buffer space 
being acquired during compilation, further 
action is necessary. The first transient 
modules then call further transient modules 
in the group to complete the DTF and get 
buffer space. These further modules are 
overlayed on the high address end of the 
first module. For certain file types it is 
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I Resident library interface routines IBMDRIO/IBMDOCN \ 


I Entry point | Function I 


| IBMBRIOA | Test statement validity and call transmitter I 
| IBMBOCNB | Bootstrap entry point to load and call error or endfile module on | 
j j first error 1 
| IBMBRIOC | Call error handler with invalid statement code I 
| IBMBRIOD j Entry from in-line code when errors detected. Branches to RIOB | 


j Transient library transmitter modules IBMDRxx I 


j Data set | File attributes I Transmitter | 
j organization | I module | 


| | | unbuffered output F-format | IBMDRAY | 
j j j buffered output F-format I IBMDRAZ | 
| | SEQUENTIAL | unbuffered input/update F-format | IBMDRBZ j 
| j j buffered input/update F-format | IBMDREW | 


| | DIRECT | F-format 1 IBMDRDZ | 


J 1 | unbuffered output F/U-format | IBMDRAW | 
| | | buffered output F/U-format | IBMDRAX | 
I I SEQUENTIAL | unbuffered input/update F/U-format | IBMDRBY | 
| j | buffered input/update F/U-format j IBMDRBX j 


| | DIRECT | F/U-format 1 IBMDRDY | 


I I I unbuffered U-format I IBMDRCY | 
| 1 j unbuffered F-format | IBMDRCZ | 
| CONSECUTIVE | SEQUENTIAL | buffered U-format I IBMDRRX | 
I I I buffered V-format I IBMDRRY | 
| I I buffered F-format I IBHDRRZ | 
| j j associated file f-format I IBMDRRW j 
j 1 j associated file v-format j IBMDRRV | 
| II associated file u-format I IBMDRRU | 
| | | OMR file F-format I IBMDRRT | 
| | j error and end-of-file exit module j IBMDRRR j 


I | SEQUENTIAL | input/update F-format I IBMDRJZ | 
j | | output F-format I IBMDRLZ | 


| | DIRECT | input/update F-format I IBMDEKZ I 


| VSAM | SEQUENTIAL | buffered/unbuffered input/output/ | IBMDRVZ | 
| (entry j j update I | 
| sequenced) | j j j 


i VSAM | DIRECT buffered/unbuffered input/update I IBMDRVR | 
| (key-sequenced) j SEQUENTIAL buffered/unbuffered input/update | IBMDRVS | 
I | SEQUENTIAL buffered/unbuffered output I IBMDRVT | 



Fiqure 8.9. Record I/O transmitters and their associated file types 
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r 

| Name | Function 


Access method 


1 ENDFILE module 




j IBMDREFI Calling error handler for ENDFILE condition if general error 
| | module has not been loaded. 


Any 


{ General .error., modules 




| IBMDREZI Calling error handler, for buffered consecutive files 


SAM 


1 1 

| IBMDBEXI Calling error handler, for indexed files 


ISAM 


1 1 

| IBMDREYI Calling error handler, for regional files and 
| | unbuffered consecutive files 


DAM 

SAM (workfiles) 


1 1 

| IBMDREYI Calling error handler for all errors (VSAM files) 


VSAM 



Figure 8.10. PL/I transient library error modules 



necessary to call a thir 
overlayed on the second, 
for the interrelationshi 
After the second and, po 
module has been exectued 
to the first transient m 
OPEN macro instruction a 
transmitter. The first 
the open/close bootstrap 



d module which is 
See figure 8.11 
p of these modules, 
ssibly, third 

a return is made 
odule to issue the 
nd load the library 
module returns via 

to compiled code. 



Space for the open modules and for 
buffers is acguired in non-LIFO storage. 
IBMDOCL acguires 2K bytes for the transient 
open routines and, if buffer space is 
reguired and the length of buffers was 
known at compile time, also acguires 
sufficient storage for buffers. 

The transmitter is only loaded if it is 
not already in main storage. (A test is 
made on the chain of loaded modules to see 
if it is.) If the transmitter is not 
already loaded it is overlayed on the high 
address end of the first transient module. 
It is moved down until the end of the 
transmitter is contiguous with the high 
address end of the 2K acguired for the 
transient modules. The transmitter is then 
contiguous with any buffer space that may 
have been acguired by IBMDOCL. On return 
to IBMDOCL the unused space left in the 
original 2K acguirement is freed. 

If the length of the buffers to be 
acguired is unknown during compilation, 
buffer space is acguired by one of the 
transient modules. When this occurs an 
unused free area will normally be left 
between the transmitter and the buffer 
space. This is placed on the free area 
chain in the usual manner. 

The open routines also alter the 
contents of certain fields in the FCB so 



that transmission statements will not 
result in a call to the open routines, as 
would occur in the case of an implicit 
open, described below. 



Ope n ing a File Implicitl y 



Implicit open is implemented by 
manipulation of the addresses to which 
transmission statements pass control so 
that these addresses always point to the 
open/close bootstrap if the file is not 
already open. This method is necessary as 
it is not always possible to determine 
during compilation which transmission 
statements will result in the opening of 
the file. (Implicit open is further 
explained under "Transmission Statements" 
below, and in figure 8.13.) 



Transmission Statements 



Compiled code calls the transmitter 
interface module IBMDRIO, passing to it the 
parameter list described above under the 
heading "Library-call record I/O 
statements" in the section "Compiler Output 
for Record I/O. " 

The interface module, IBMDRIO, first 
acguires a DSA, which is used both by 
IBMDRIO itself, and by the transmitter. It 
then initializes the registers and executes 
the instruction in the reguest control 
block (RCB) . If the transmission statement 
being executed has been tested and found to 
be valid, the instruction will be a branch 
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o 



KEY 



OPEN and CLOSE 

statements 



TRANSMISSION 
statements 



IBMDRIO 
IBMDOPA 



¥.-• 



Names not in italic in resident library 

Names in italic in transient library 

Call to module 

Return to calling module 

Load but ho call 



Implicit close 
Call during program 
termination to 
close any files, 
still open 



IMPLICIT OPEN 



IBMBOCNC 

Invalid 

statement 

routine 



J 



(See fig 8.13) jnva|jd 
^_FAIS 4^ 



IBMDOCL 

Open/close 
bootstrap 



IBMDERR 



IMPLICIT OPEN 



statement 



Call from WAIT module 
for EVENT I/O 



IBMBRIOA 
I nterface 



IBMBOCNB 

Error 

module 

bootstrap 



IBMDOPM 



Consec. 
Unbuff. 



IBMDOPP 



Consec. 
Buff. 



«-r* 



IBMDOPV 



Open VSAM 



IBMDOPQ 



Get buffers and 
init. DTF (not 
disk or tape) 



IBMDOPS 



Stream 



t 



IBMDOPT 



Get buffers and 
init. DTF (not 
disk or tape) 



IBM DOPY 



Get buffers and 
init. DTFDA 



IBMDOPU 



Init. DTF for 
disk or tape 



IBMDOPZ 



Get buffers and 
init. DTFIS 




FATM 
[See fig 8.13) 



IBMDERR 

Execute on- 
unit or standard 
system action 



1 



IBMDREF/V 
Endfile routine 
Call error 
handler for 
Endfile 



^ FERM 
(See fig 8.14) 




IBMDRE/X/Y/Z 

Record I/O 
error support 
module 



Returns to compiled code or WAIT module 



Figure 8.11. Organization of record I/O library modules 



DTF 



LIOCS TRANSMITTER <4- 



A(LIOCS transmitter) 



(Address set only for files that can 
use in-line I/O). 



FCB 



PL/I TRANSMITTER + 



I 



—J > 

/ / 

/ / 

/ / 

/ / / 

' / / 
/ / / 

/ / ' 

I'' 



/ / 



FATM A(Transmitter) 



FAIS A( I rival id stmt) 



INVALID STATEMENT 

(Entry point G of IBMBRIO) 



OPEN/CLOSE BOOTSTRAP 



Key 



-► Address when file closed 
-► Address when file opened 



Figure 8.13. Implicit open procedure 



instruction. If the statement has not been 
tested, or has been found to be invalid, 
the instruction will be a TM instruction. 
If the statement is valid, control will be 
passed directly, or after the TM 
instruction, to the address in the FCB 
field FATM. If the statement is invalid, 
control will be passed to another address, 
in the FCB field "FAIS." 

As is shown in figure 8.13, the 
addresses held in these words depend on the 
condition of the file. 

If the file is open, FATM contains the 
address of the PL/I transmitter, and FAIS 
contains the address of an entry point in 



the interface module, IBMBRIOC, which 
results in a call to the error handler. 

Therefore, if the file is open, the 
transmitter will be called if the statement 
is valid; the error handler will be called 
if the statement is invalid. 

If the file is not open, both FATM and 
FAIS contain the address of the open/close 
bootstrap routine IBMDOCL, entry point 
IBMBOCLC. 

Therefore, if the file is not open, the 
execution of any transmission statement 
will result in a branch to the open/close 
bootstrap routine. The open/close 
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OPEN Statements 

1 Complete the DTF and the FCB for 
the file if necessary, or 
generate the ACB for VSAM files. 

2 Obtain storage for buffers, 
index areas, etc. if necessary. 

3 Issue the data management OPEN 
macro instruction. 

4 Raise the ONDEFINEDFILE 
condition if the file cannot be 
opened. 

Transmission stateme nt s 

1 Branch to the open routines if 
the file is not open. 

2 Ensure that the statement is 
valid for the file. 

3 Check the record and key 
variables for errors. 

4 Issue the appropriate data 
management macro instruction. 

5 Move the data between the buffer 
and the record variable if 
necessary. 

6 Raise any conditions that occur 
during the execution of the 
statement. 

CLOSE statements 

1 Ensure that all operations 
commenced on the file have been 
completed. 

2 Issue data management close 
macro instruction. 

3 Release any storage allocated to 
the file, e.g., I/O transmitter 
space. 

No te : The functions are not 

necessarily carried out in the 
above order. 



Transmitter Action 



After the file is open and the statement 
validated, control is passed to the 
transmitter, which checks the record and 
key variables for errors, and issues the 
appropriate data management macro 
instruction. After data management has 
handled the request, control returns to the 
transmitter. The transmitter moves the 
data between the data management buffer and 
the record variable, or sets the pointer to 
the record, and checks to see whether any 
errors have occurred. 

Transmitter modules do not acquire a DSA 
but use the DSA acquired by IBMDRIO. 

For VSAM files a further control block, 
the IOCB (Input/Output Control Block) 
provided by OPEN, is used, in preference to 
the FCB, to hold information relating to 
the current statement. Space is provided 
in the IOCB for MODCB & SHOWCB parameter 
lists used respectively to modify and 
display the various fields in the data 
management RPL (Request Parameter List) , 
which is passed to the VSAM LIOCS routine 
for any action macro. (See Appendix B for 
details of tfhe IOCB). The transmitter 
action is essentially similar to that for 
other access methods. It is worth noting 
that a READ INTO will generally be 
implemented by means of a VSAM GET macro 
directly from the system buffer to the 
record variable. If the record variable is 
too short, VSAM will give a logical error 
return code and no transmission will take 
place, where upon the PL/I transmitter will 
reissue the request, providing an 
intermediate dummy buffer, and finally move 
the truncated record to the record 
variable. 



Figure 8.12. Summary of work done by 
PL/I library routines 



Raising Co nditions i n Transmission 
Statements 



bootstrap routine calls the transient 
library open routines, which open the file, 
and alter the contents of FATM to point to 
the transmitter, and of FAIS to point to 
the error entry point IBMBRIOC. When the 
file is open, control is returned to the 
interface module and execution of the 
transmission statement is reattempted. 



To enable PL/I error handling to be 
available yet cause the mimimum possible 
overhead to error-free programs, transient- 
library modules are provided which are not 
loaded unless an error occurs. Two modules 
| are available for all file types except 
VSAM file. VSAM files use one error 
| module, IBMDREV and this handles both 
J errors and end-of-file situations. The 
following discussion does not therefore 
apply to VSAM. The two types of error 
sorting used for non-VSAM files are: 



Implicit open for record I/O statements 
handled by in-line calls to data management 
are handled in a similar manner. 



1. The ENDFILE routine, IBMDREF, which 
can deal only with the ENDFILE 
condition. 
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Contents F EFT 

Initialized by open routine with 

character "X", "Y", "Z" or "V" 
indicating general error support 
module. 

Altered for non-VSAM files 
by EOFADDR routines in 
transmitter to character "F" 
indicating ENDFILE module. 
Restored by ENDFILE mod- 
ule to "X", "Y" or "Z" when 
non-endfile error found 



Contents FEMT 
Always contains character 
indicating general error 
support module 




IBMDRIO 

(entry point C) 
Loads and calls module 
indicated in "FEFT" and 
places its address in FERM. 



IBMDREF 

Endfile module 
If ENDFILE : 
Calls er/or handler 
If other error : 
Loads and calls 
error module indicated 
in "FEMT". Placing 
address in FERM 



IBMDRE/X/Y/orZ 

General error support module. 

Handles all errors including 
ENDFILE 



IBMDREV 



All errors for VSAM files 



Key 



If no errors have occurred. 

If 1st. error was ENDFILE and 
no other errors occurred. 

If non-ENDFILE errors have 

occurred. 

VSAM files 



Figure 8.14. If conditions are raised during transmission, flow of control 
depends on the contents of the FCB field FERM 
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2. A general error module (one for each 
access method - see figure 8.10). 
This module is capable of handling all 
conditions that may arise, including 
ENDFILE, but is loaded only if the 
TRANSMIT, RECORD, KEY, or ERROR 
condition occurs 

These transient error modules are all 
identified by the six letters IBMDRE 
followed by a further single character (see 
figure 8.10) . 

If a transmission error occurs, the 
transmission error routine within the 
transmitter will be entered, whether an in- 
line or library-call statement is being 
executed. Similarly, if end-of-file 
occurs, the end-of-file routine within the 
transmitter will be executed. Record and 
key errors are detected either by the 
transmitter or by compiled code. 

When any of the errors or PL/I 
conditions mentioned above occurs during 
the execution of a record I/O statement, 
control is passed to the address held in 
the word "FERM" in the FCB. This address 
may be any one of the following: 

1. The address of IBMDREF, the ENDFILE 
module. 

2. The address of the general error 
module for the file type. 

3. The address of a bootstrap routine, 
IBMBOCNB. This routine constructs the 
name of an error module by taking the 
skeleton IBMDRE*A and replacing the 
"*" by the letter in the single 
character field "FEFT" in the FCB. 
IBMDRIO then places the address of 
this module in FERM, and branches to 
the module it has loaded. 



file. 

The result of this arrangement is that 
the general error module can be called in 
an end-of-file situation. Similarly, the 
ENDFILE module can be called when another 
type of error occurs, if ENDFILE was the 
first condition to occur. 

To overcome this problem, the general 
error module contains code to handle 
ENDFILE, and the ENDFILE module contains 
code to test for other conditions, and load 
and call the general error module if 
appropriate. 

The ENDFILE module restores the 
character in 'FEFT' from the field » FEMT» 
land calls IBMBOCNB. FEMT always holds the 
character that identifies the general error 
module for the file. When the name has 
been constructed, the general module is 
loaded, its address is placed in FERM, and 
a branch is made to the module. 

The process is illustrated in figure 
8.14. 



Gen eral Err or Ro ut ines (Tr ansient ) 



The general error routines set up a 
parameter list, and branch to the resident 
error-handler, IBMDERR, to handle the 
condition. If a normal return is made from 
an on-unit, the general error module will 
raise any further conditions that have 
occurred. After all conditions have been 
raised, a return is made to compiled code, 
or, in EVENT I/O, to the WAIT module. 



Thus by changing the contents of the field 
"FEFT", the transmitter can select a 
particular error module. The contents of 
"FEFT" is one of the following: 

1. A character indicating the name of the 
general error module for the file 
type. This character is placed in 
"FEFT" during the execution of the 
OPEN statement. 

2. The character "F", indicating the name 
of the ENDFILE module. The content of 
"FEFT" is changed to "F" by the end- 
of-file routine in the transmitter 
(which is entered when data management 
detects end-of-file) . 

Thus the module loaded by the bootstrap 

| routine IBMBOCNB, and the address placed in 

"FERM", depends on whether end-of-file or 

another error is the first to occur on the 



ENDFILE Routine 



The ENDFILE routine checks to ensure that 
the situation which has resulted in the 
call is really end-of-file, and, if so, 
passes control to the error handler. 



CLOSE Statements 



Files and data sets can be closed either by 
the PL/I CLOSE statement or by the 
termination of the program. In both cases, 
the close is carried out by the library 
routines. The bootstrap module IBMDOCL is 
called at entry point C or D, and it loads 
and calls the close routine, IBMDOCA. If 
| any VSAM files are found, IBMDOCA loads and 
calls IBMDOCV. 
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The bootstrap routine is passed a 
parameter list containing the addresses of 
the FCBs for the files that require 
closing. IBMDOCA then closes these files. 
This may involve completing I/O operations 
and hence calling the transmitter. After 
handling any necessary transmission, 
IBMDOCA disassociates the file from the 
data set. If the transmitter was being 
used only by the file that is being closed, 
the storage for the transmitter is freed. 
A check is kept on the use of transmitter 
and other transient modules in a sixteen 
byte prefix at their head. The value held 
in this field is set to one when the 
transmitter is loaded, and decreased or 
increased as new files requiring the 
transmitter are opened. For implicit 
closing, the chain of open files starting 
in the TCA is scanned to determine which 
files must be closed. 

When IBMDOCA has finished, it returns 
control (via IBMDOCL) either to compiled 
code (for an explicit close statement) or 
to the termination routine (for the end of 
the program) . 



flag in the FCB and return to compiled 
code, normally via the LIOCS routine, if 
the error flag is on, or if the RECORD 
condition has occurred, compiled code 
branches to IBMBRIOD. This results in a 
call being made to the transient error 
module. 

Typical code produced for an in-line I/O 
statement is shown in figure 8.6. 



Control Blocks for In-Line Calls 



For in-line I/O statements, the only 
control blocks that are set up are the FCB 
and DTF. The request control block, and 
record and key descriptor are not reguired 
as the information is known during 
compilation and suitable code to move the 
data to or from the record variable can be 
generated. The RCB is not generated, as it 
is required only by the library routines to 
determine the statement type when checking 
statement validity. 



If any VSAM files are found by IBMDOCA 
it makes a call to IBMDOCV for each VSAM 
file found. IBMDOCV then carries out 
similar action to IBMDOCA for the file. 
IBMDOCV is loaded for the first VSAM file- 
found. The space it occupies is freed by 
IBMDOCA before returning to IBMDOCL* 



In-Line I/O Statements 



Most transmission statements on buffered 
consecutive files are implemented by in- 
line calls to the LIOCS routines (see 
figure 8.2 for details). Such statements 
are referred to as "in-line I/O 
statements." Only READ, WRITE, and LOCATE 
statements are handled in this way. OPEN 
and CLOSE statements a lways result in 
library calls. 

For in-line I/O, a call is made direct 
to the data management LIOCS routine whose 
address is held in the DTF. The DTF is 
addressed from the FCB. In addition to 
calling the LIOCS routine, compiled code 
moves the data as necessary to or from the 
record variable, or sets appropriate 
pointers. Compiled code may also check for 
the RECORD condition. 



Implicit Open for I n- Line Calls 



Implicit open for in-line calls is handled 
in a similar way to that used for library 
calls (described above). 

For a compiled code call, the address in 
the DTF that normally holds the address of 
the data management LIOCS transmitter is 
initialized to point to the open/close 
bootstrap routine, IBMDOCL (see figure 
8.13). When the open routines have 
finished, the address in the DTF is altered 
to point to the LIOCS routine. 

If the file is successfully opened,' a 
test is made to see whether the entry to 
IBMDOCL was for an in-line call and, if it 
was, control is passed to the data 
management address held in the DTF. For 
input, this causes the LIOCS transmitter to 
be entered and a return made to compiled 
code. For output, it will cause entry into 
code in the PL/I library transmitter which 
places the address of the LIOCS transmitter 
in the DTF and returns to compiled code. 
This is the normal transmitter action for 
the first output statement. 



If there is an error in transmission, or 
if end-of-file is reached, the LIOCS 
routines will branch to the ERROPT or 
EOFADDR routines that are held in the PL/I 
transmitter. (The PL/I transmitter is 
always loaded by the open routines.) The 
ERROPT and EOFADDR routines set an error 



Event I/O 



Event I/O is fully described in chapter 11, 
under the heading "The WAIT Statement." 
The principles are described briefly below. 
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P : PROC; 



READ. . . .EVENT (E); 
< 



1 



<- 



IBMDRIO 



I 

-^ 1- 

PL/I TRANSMITTER ' 



— 1> 



ISSUE DATA MANAGEMENT - 

MACRO 

RETURN IF EVENT I/O 

ISSUE WAITF MACRO < 

i 

I 



TEST FOR ERRORS 

IF NONE RETUR'N TO WAIT 

MODULE 



i 
V 



V 

I 
I 



WAIT(E); — - 
k] 






WAIT MODULE 

IF EVENT I/O CALL IBMDRIO 



\LL IBMDRIO ^-> 



RETURN IF NO MORE 
EVENTS TO WAIT ON 



END P; 



Key 



^ READ EVENT statement 

> ■ WAIT statement 

Further PL/I statements 



"I 

I 

I 

I 

I 

I 
A 



I 
I 



Figure 8*15. Plow of control for READ, EVENT and WAIT statements 
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SOURCE 
PROGRAM 



Open 
statement 



COMPILATION 



Transmission 
I/O statement 



Generate code 
to call open 
bootstrap 



Set up RCB 
for Execution- 
Time test 



Generate 
call to 
IBMDRIO 



Key 






Path using library calls 
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Figure 8.16. Overview of record I/O implementation 
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If the EVENT option is used in an I/O 
statement, the statement will be handled by 
a library call. Thus control will be passed 
from IBMDRIO to a PL/I library transmitter. 
This transmitter returns control to 
compiled code as soon as the data 
management macro instruction is issued. 
When the WAIT statement nominating the 
event is reached by compiled code, a call 
is made to the WAIT module which returns 
control to the transmitter via IBMDRIO. 

A WAITP macro instruction is then 
issued, and control is returned to the 
transmitter when the input or output 
operation is complete. The transmitter then 



tests for errors and, providing no errors 
have been detected, returns control to the 
WAIT module, which returns control to the 
next statement. 

For VSAM files EVENT I/O is simulated. 
The return code from data management is 
tested by the transmitter immediately after 
issuing an action macro instruction. 
However, any errors detected are held over 
until the corresponding WAIT statement is 
issued when control is returned to the 
transmitter. 

Figure 8.15 illustrates the principles 
used in EVENT I/O. 
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Director routines control the 
process, calling necessary 
conversion and transmitter 
modules when required. 



Variable I (Fixed Binary 15,0) 
(in main storage) 



Stream input/output is a two stage process. The data is moved between the external medium and the data management buffer, and 
between the buffer and the variable. Any necessary conversions are made between the buffer and the variable. The operation is 
controlled by director modules. The director modules call the appropriate routines to do the transmission and conversion. Transmission 
is carried out in a similar way to that used for RECORD I/O. 

Note that a further input statement will require the value 9 which is already in the data management buffer. Consequently the trans- 
mitter need not be called and a pointer must be kept to the position reached in the buffer. 



Figure 9.1. Conceptual diagram of stream I/O 



114 



Chapter 9: Stream-Oriented Input/Output 



Note on Terminolo gy 



In this chapter, the terms source and 
target are used when referring to transfer 
of data. The source is the point from 
which the data is taken; the target is the 
point to which it is moved, possibly in a 
converted format. 



if they span the record boundary. 
Similarly, because GET and PUT statements 
may read or write less than a complete 
record, a method is needed of keeping track 
of the position reached in the record, so 
that the next GET or POT can start from the 
correct position. 



Introduction 



Operati ons in a Stream I/O Statement 



PL/I stream-oriented input/output allows 
the programmer to move data between a PL/I 
variable and an external medium without any 
concern about internal and external data 
types or any attention to record 
boundaries; both conversion and record 
boundary problems are handled 
automatically. 

Although it appears to the programmer 
that the data is moved directly between the 
external medium and the PL/I variable, the 
move is in fact a two stage process, as 
shown in figure 9.1. In the first stage, 
the data is moved to a data management 
buffer, in the second stage, it is moved 
from the buffer to the target. When the 
data is moved to or from an external 
medium, a complete record is always moved. 
When the data is moved to or from a PL/I 
variable only as much data as is contained 
in the variable is moved. The amount of 
data moved in the one stage need bear no 
relation to the amount moved in the other. 
Thus synchronization of the two stages is 
the principal job in implementing stream 
I/O. 

Transmission between the buffer and the 
external medium is handled by the LIOCS 
routines of data management. These 
routines are called by PL/I transient 
library transmitters in a way similar to 
that used in library call record I/O. The 
movement between the buffer and the PL/I 
variables is generally handled by the PL/I 
conversion routines. 

Data items transmitted by stream I/O are 
not affected by record boundaries (see 
figure 9.2). There may be any number of 
data items in a record, and an item may 
span any number of records. Because the 
LIOCS routines make only one record 
available to the program at any one time, a 
method is needed to build up complete items 



A stream I/O operation can involve any or 
all of the following opertions: 

1. Opening the file, and raising the 
ERROR condition if the statement is 
invalid. 

2. Keeping track of the position in the 
buffer. 

3. Calling the transmitter for a new 
record. 

4. Building in intermediate workspace an 
item too large to be held in the 
current record. 

5. Determining which conversion is 
reguired, and calling the routine to 
carry out the conversion. 

Control of operations (2) through (5) is 
handled by director routines . For list- 
directed and data- directed I/O, PL/I 
library director routines are used. For 
edit-directed I/O, the job is shared 
between library routines, compiler- 
generated subroutines, and compiled code. 

Before the director module or director 
code receives control an initialization 
module is called. This module handles item 
(1) in the list above: checking statement 
validity, and opening the file if it is not 
already open. 

Because there are three modes of stream 
I/O, the exact situation cannot be defined 
in a generalized discussion or diagram. 
However, the basic principles are shown in 
figure 9.3. The sequence is: 

1. A call to the initialization module. 

2. A return to compiled code. 

3. A call to the director module. 
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Figure 9*2. Record boundaries do not affect stream I/O 
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Figure 9,3. Generalized flowchart of a stream input statement 
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Stream I/O Control Block 



Transmission 



To simplify communication between the large 
number of routines that may be used in a 
stream I/O operation, a control block is 
set up for the duration of execution of the 
stream I/O statement. This control block 
is known as the stream I/O control block 
(SIOCB) . The contents of the SIOCB are 
shown in figure 9.4. 
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Figure 9.4. Stream I/O control block 
(SIOCB) 



Basically, the SIOCB consists of the 
addresses of the source and target (or 
their locators) , of the DEDs of the source 
and the target, and of various other items. 
The SIOCB can be passed directly to the 
conversion modules, because the first four 
words are the same as the parameters 
expected by the conversion routines. 



File Handling 



In stream I/O, file organization is always 
seguential and the access method used is 
the gueued seguential access method (QSAM) , 



Transmitters are called by the director 
modules or by the close module to complete 
transmission when the program is 
terminated. 

As with record I/O, LIOCS transmitters 
are used, and they are called by PL/I 
transmitters. The PL/I transmitters 
contain the ERROPT and EOFADDR routines, 
which are entered when end-of-file or other 
errors are detected in the LIOCS routines. 
Seven different transmitter modules are 
used in stream I/O; they are listed in the 
summary of subroutines at the end of this 
chapter. 



Openin g the File 



The same basic method is used for opening 
the file as is used for record I/O. During 
compilation, a def ine-the-file control 
block (DTF), a file control block (FCB), 
and an environment control block (ENVB) are 
set up. At open time, the information 
addressed from the ENVB is used to complete 
the FCB and DTF, the PL/I transmitter is 
loaded, and its address is placed in the 
FCB. The LIOCS routine to be used is 
determined during compilation, and link- 
edited. 



Imp licit Open 



Implicit opening is handled by the 
initialization routines, which check to see 
whether the file is open and, if not, call 
the open/close bootstrap routine IBMDOCL. 

The FCB for stream I/O is similar to 
that used for record I/O. However, it 
contains certain additional fields which 
are needed only for stream I/O. The most 
important of these fields are the buffer 
control fields- 



Keepin g Track of Buffer Position 



Two fields in the FCB are used to keep 
track of the position which has been 
reached in the data management buffer, and 
to indicate when a new record will be 
reguired. These fields are the buffer 
control fields: 

1. FCBA - pointer for position reached in 
current record. 
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FREM 
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FREM 
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Figure 9.5. The FCBA and FREM fields of the FCB 



2. FREM - number of unused bytes 
remaining in the record. 



FCBA points at the position reached in the 
record and enables the director routines to 
identify where the next input item must be 
read from, or where the next output item 
must be written. FREM contains the number 
of bytes left in a record. It enables the 
director modules to determine when a new 
record will be required, and whether an 
item is too large to be held in the 
remainder of the record and will 
consequently require intermediate 
workspace. Figure 9.5 illustrates the use 
of FCBA and FREM. 



Handling the Conversions 



Conversions in stream I/O are normally 
handled by the library conversion package. 
The conversion package, described in 
chapter 10, consists of conversion routines 
and conversion director routines. 
Conversion director routines examine the 
DEDs of the source and the target passed in 
the argument list (i.e., the SIOCB, for 
stream I/O) , and determine which entry 
point of which conversion module is 
required. Each conversion has a unique 
entry point. 

A number of conversion director modules 
are used exclusively by edit-directed 
stream I/O. These are called ext ern al 
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conversion di rectors , and are listed in the 
summary of subroutines at the end of this 
chapter. Each module corresponds to a 
particular format of input/output. When 
the type of input or output has been 
determined by the director modules, the 
appropriate conversion director routine can 
be called to handle the conversion. 

In edit-directed I/O, the conversion 
required is normally predictable during 
compilation, because it is implied in the 
format list. Consequently, the conversion 
modules can be called from compiled code 
rather than from the stream I/O director 
routines. Alternatively, compiled code may 
handle the conversion in-line. 

When a library conversion module is 
required by compiled code, the conversion 
director module may be called, or the 
conversion module itself may be called. 
When the conversion module is called, 
compiled code must carry out the jobs 
normally handled by conversion director 
modules, that is, setting up a number of 
fields that are used mainly in handling 
CONVERSION and other PL/I conditions. 



Handling GET and PUT Statements 



There are considerable differences in 
detail between the handling of GET and POT 
statements for the three different modes of 
stream I/O. However, they all follow the 
basic scheme in figure 9.3 and summarized 
above under the heading "Operations in a 
Stream I/O Statement." 

The implementation of GET and PUT 
statements is covered in some detail below 
for list-directed I/O. For data-directed 
and edit-directed I/O, the differences from 
list-directed are highlighted. 



List-Directed GET and PUT Statements 



PUT LIST Statement 



Implementation of a list-directed output 
statement is shown in figure 9.6* The 
process consists of four steps: 

1. Compiled code calls the initialization 
routine, passing the address of the 
FCB and of the SIOCB, in which 
compiled code has set flags indicating 
the statement type. 

2. The initialization routine, IBMDSIO, 
calls the open routine if the file is 



not open, and checks the validity of 
the statement. If the statement is 
invalid, a branch is made to the error 
handler, passing an error code 
indicating "invalid statement." This 
results in a message being generated, 
and the ERROR condition being raised. 
If the statement is valid, control is 
returned to compiled code. 

IBMDSIO also handles any format 
options, by calling the formatting 
module IBMDSPL. Control then returns 
to compiled code. 

3. Compiled code places the address of 
the source (or its locator, if the 
item is a string) and the address of 
the source DED in the SIOCB. (See 
chapter 4 for information on 
locators.) Compiled code then calls 
the director module. 

4. The director module completes the 
SIOCB with the address of the target 
locator and the address of the DED of 
the target. The target locator gives 
the length required for the item. As 
the target is always a character 
string, a locator will always be used 
for it. The address of the target is a 
position in the buffer. For PRINT 
files, the position is indicated in 
the tab table, which will either have 
been set up by the programmer by use 
of PLITABS, or be the default tab 
table in the library module IBMBSTA. 
For non-print files, a one-byte space 
follows each item. When the starting 
postion for the item has been 
determined, the director module 
determines whether there is enough 
space in the output buffer for the 
converted item. If there is not, the 
director determines whether this is 
because there is no room left in the 
buffer, in which case it is simply a 
new record that is needed, or because 
there is insufficient room in one 
buffer, in which case the item will 
have to span a record boundary. 

If it is simply a case of acquiring a 
new record, the director calls the 
transmitter to acquire it. The 
director then calls the appropriate 
conversion routine, passinq it the 
SIOCB as a parameter list. The 
conversion rojutine will then move the 
data from the PL/I variable to the new 
record in the data management buffer. 

If, however, the converted item will 
span the boundary between the current 
and subsequent records, intermediate 
workspace is acquired in the form of a 
VDA (variable data area) . The 
converted item is then placed in the 
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The initialization routine is passed the address of the 
FCB and the address of the SIOCB. 



It opens the file if necessary and acquires the first 
record for print files. If the statement is invalid it 
calls the error handler. If the statement is valid it 
places the addresses of the ONCA and the FCB in 
the SIOCB and returns to compiled code. 



Figure 9.6. List-directed output statement 
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The director module calls the transmitter and 
conversion modules when required and handles 
any housekeeping problems. 



Before calling the conversion module it completes 
the SIOCB with the address of the target locator 
and the address of the target DED. 
The target for the conversion is either the data 
management buffer or a VDA acquired for 
intermediate workspace. 



If the statement is complete compiled code continues 
with the next statement. If the statement is not complete 
compiled code places new data in the SIOCB and once 
more calls the director module. 
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Store in parameter list 
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Figure 9.7. Typical code generated for a PUT LIST statement 



VDA. As much of the data as will fit 
is moved into the data management 
buffer, and a new record is acguired 
by a call to the output transmitter. 
The new record is then filled. This 
process is continued until the 
complete item has been moved into 
buffers. Finally, FCBA and FREM are 
updated. 



If there are further data items to be 
handled, a return is made to step (2) , and 
the address of a new source field and its 
DED are placed in the SIOCB. This process 
is continued until all items in the data 
list have been processed. The object code 
produced for a PUT LIST statement is shown 
in figure 9.7. 



GET LIST Statement 



GET LIST statements follow the same 
sequence, but the transmission is in the 
opposite direction. The main differences 
are: 

1. If record spanning is involved, the 
item is assembled in intermediate 
workspace before it is converted. 

2. A locator is built for the source 
string from the input, and the 
addresses of the locator and of the 
DED for the source are placed in the 
SIOCB by the director module. For 
input, the address of the target or 
its locator and the address of the 
target DED are placed in the SIOCB by 
compiled code. 

3. FCBA and FREM are updated before the 
item is converted. 
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GET DATA (A,B); 

PI niAl niARRAM 










COMPILED CODE & NOTES 

LA 0,40(0,4) Pick up address of SIOCB 
ST 0,136(0,3) Place in p - list 
01 136(3),X'80' flag last argument in p - list 
MVI 57(4),X'84' Set flag 'DATA INPUT' in 

SIOCB 
LA 15,56(0,3) Set abnormal return 
ST 15,64(0,4) address in SIOCB 
LA 1,132(0,3) Point R1 at p - list 
L 15,A. . IBMBSIIA Branch to stream 
BALR 14,15 initializing module 


From Step 6 

\3 ; 




Step 4 

Data - directed director 

module IBMBSDI 




The data directed director module is passed the 
address of the SIOCB and either a list of symbol 
table addresses or an address in the symbol table 
vector. 

The module reads in the name, checks that the 
name read is in the symbol tables passed and if 
not raises the NAME condition. 

When the variable is identified the module places 
the address of the target and its DED in the SIOCB 
and calls the list-directed director module passing 
it the SIOCB. 




t 


Stepl 
Compiled code 


X record X t 
\^ or spanning?/ "" 


Call transmitter 
setting up VDA 
if necessary 






Set up parameter 
list, call 
initializer 






1 








./Name\^ 
/S in data \ NO 
\ stream match y w 
\SYIvlTAB?/ 


Call IBMBERR 








r 






lYES 










Place address 
DED and variable 
in SIOCB 








Step 2 

Input initializing module 

IBMBSII 


The input initializing module is passed the 
address of the SIOCB and the FCB for the file. 

It checks the validity of the statement, opens 
the file and places the address of the FCB in the 
SIOCB and returns to compiled code 




\ 










Update FREM& 
FCBA to beyond 
equal symbol 






Set fields 
in SIOCB 




t 








<^ File J> 










Call list-directed 
director module 




NO 


Call IBMBOCL 
to open file 




























1 YES 


' 


' 




Step 5 


The list directed module completes the operation as 
for list directed I/O 




Return to 
compiled code 












Decide on 
conversion 
required and call 
correct module 
















i 


' 


Step 3 
Compiled code 


LA 0,40(0,4) Pick up address of SIOCB 
ST 0,140(0,3) Place address in p - list 

p-list, containing addresses 
of symbol tables and 
variables already set up,in 
static 

LA 1,140(0,3) Point R1 at p - list 

L 15.A. .IBMBSDIA Call data-directed director 

BALR 14,15 module 

CL.5 EQU* Abnormal locate return 
address 




1 










Update FREM & 
FCBA 
Return to 
IBMBSDI 






Set up p. list 

for data 

director 

consisting of 

A(SIOCB) 

A(SYMTAB,I) 

A(SYMTAB,J) 










i t 


Step 6 


On return to the data directed module a search is 
made for the next name and the action continued 
as from step 4 until a semicolon is reached in the 
input stream 


<I 


Repeat from 
step 4 until 
final semicolon 
found 






I 




















Return to compiled code 











to 



Figure 9.8. Data directed input statement 



* STATEMENT NUMBER 3 


0000A4 


41 


90 





0C8 


OO0OA8 


50 


90 


3 


044 


OOOOAC 


96 


80 


3 


044 


OOOOBO 


92 


80 





009 


OOGOB4 


92 


01 


D 


OOA 


0000B8 


41 


10 


3 


040 


OOOOBC 


58 


FO 


3 


24 


OOQOCO 


05 


EF 






0000C2 


41 


90 


D 


0C8 


0000C6 


50 


90 


3 


048 


OOOOCA 


96 


80 





ODB 


OOOOCE 


41 


10 


3 


048 


0000D2 


58 


FO 


3 


020 


000006 


05 


EF 







LA 


9,200(0,13) 


ST 


9,68(0,3) 


01 


6813), X'80* 


MVI 


217(13) ,X«80» 


MVI 


218(13), X'Ol* 


LA 


1,64(0,3) 


L 


15,A..IBMBSIQA 


BALR 


14,15 


LA 


9,200(0,13) 


ST 


9,72(0,3) 


01 


219(13) ,X»80« 


LA 


1,72(0,3) 


L 


15,A..IBMBS00A 


BALR 


14,15 



Load address of SIOCB 
Store in parameter list 
Mark end of parameter list 
Set flags in SIOCB 

Point Rl at parameter list 

Branch to initialization routine 

Load address of SIOCB 

Store in parameter list 

Set flag in SIOCB 

Point Rl at parameter list 

Branch to data-directed director routine 



Figure 9.9. Typical code generated for a POT DATA statement 



Data-Directed GET and PUT Statements 



Data-directed GET and POT statements follow 
a similar sequence to list-directed 
statements, in that there is first a call 
to the initialization module, followed by a 
call to a director routine. However, the 
data-directed director module is passed a 
means of identifying the names and 
addresses of all the variables involved in 
the statement rather than one item at a 
time. 

When the data-directed module has 
identified the location of the variable to 
or from which the data is to be moved, it 
calls the list-directed director module 
which then handles the movement of the 
value of the variable. When the value of 
the variable has been transmitted, control 
returns to the data-directed module. The 
data-directed director then handles the 
next name, determines the address of the 



variable associated with the name, and 
calls the list-directed director module to 
handle the transmission of the value. This 
process continues until the statement is 
complete. The process is illustrated in 
figure 9.8. 

The list-directed director module is 
called separately for each item. It is 
passed the SIOCB with the addresses of the 
source or target (or its locator) and the 
address of its DED correctly set up by the 
data-directed director module. The item is 
then handled as if it were a list-directed 
item. 

If a data list is included in the 
statement, the source or target variables 
are identified from a list of symbol 
tables. If no data list is included in the 
statement, they are identified from the the 
symbol table vector. 

A symbol table associates a name with 
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the address of a variable. The symbol 
table vector for an external procedure is a 
list of the symbol tables known in the 
external procedure. The list is arranged 
in program block order. When a symbol 
table vector is used, the address passed is 
the start of entries for items known in the 
current block. Symbol tables and the 
symbol table vector are described further 
in chapter 4. Their format is shown in 
appendix B. 

The object code produced for a POT DATA 
statement is shown in figure 9.9. 



Edit-Directed GET and PUT Statements 



Edit-directed I/O differs from the other 
modes of stream I/O in that the conversions 
reguired and the positions in the record 
where an item is to be placed or will be 
found are indicated in the format list of 
the I/O statement. 

The format list contains two related 
types of information: 

1. The type and length of the item (e.g., 
F(3), A (25), etc.), known as data 
f ormat i n formation. 

2. Spacing information (e.g. , 

X(3) , COL (70) ,etc.) , known as control 
format information. 

Both types of information are compiled as 
format ...DEPs (FEDs) and are passed by 
compiled code to the routines that reguire 
the information. 



2. Handling X format control items, 

except where a new record is required. 



These compiler-generated subroutines have 
the advantage over library modules that 
they are not external, and consequently do 
not have to follow the external calling 
conventions. 

The compiler-generated subroutines are 
supported by two types of library director 
module: 

1. Two short modules, IBMPSEO and 
IBMPSEI, that interface with the 
transmitter and are called by the 
compiler-generated subroutines when a 
new record is required. 

2. Three routines that handle the 
complete processing of an item (as 
does the director for list-directed 
I/O) . These routines are called when 
an item cannot be handled by compiler- 
generated subroutines. 

IBMDSED is used only when complex data 
or format items appear in the program. 

IBMDSEE is used when both GET and PUT 
EDIT statements are used in the 
program and no complex data or C- 
format items appear. This routine 
contains the functions of the 
formatting module IBMPSXC and the 
conversion director modules 
IBMBSFI,IBMBSFO, and IBMBSAO, and the 
A-format function of IBMBSAI. 
Consequently, it normally uses less 
space than IBMDSED which calls these 
modules. 



Because the information is available 
during compilation, it is normally possible 
for the compiler to determine the 
conversions that will be required. 
Consequently compiled code can call the 
required conversion or conversion director 
routine, or qenerate in-line conversion 
code without the assistance of a library 
director module. 



Compiler-Ge nerated Subroutines 



To further optimize edit-directed I/O, a 
number of compiler-generated subroutines 
have been provided. They carry out the 
following functions: 

1. Keeping track of the buffer position, 
freeing and acquiring intermediate 
workspace where necessary, and calling 
the library when a new record is 
reguired. 



IBMDSEH is used when only edit- 
directed output is Used in a program 
and no complex data is used. IBMDSEH 
is similar to IBMDSEE but does not 
contain the input code. 

The superset/subset feature of the linkage 
editor ensures that only one of the modules 
is link-edited if ESD references are made 
to IBMDSEE and IBMDSEH. IBMDSED can handle 
all situations, and IBMDSEE can handle any 
situation handled by IBMDSEH. 

The decision on whether to use compiler- 
generated subroutines or the overall 
library director module is made at compile 
time. Figure 9.10 shows the conditions 
under which each method is used. 

A typical edit-directed statement takes 
the form: 

1. A call to the initialization module to 
open the file (if necessary), and 
check statement validity. 
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Handle entirely by library 
routine or use compiler- 
generated sub-routines? 



COMPILER 

Compiler-generated subroutines are used 
except in the cases shown opposite. Even so, 
a library routine will be called if a new record 
is required, and, generally, to handle a con- 
version. 



LIBRARY 

Handles processing completely for: 

Negative or zero field widths in format specification 
A-format item with implied length on output* 
B-format item with implied length on output 

* An exception is that A-format items with implied length are 
handled in-line if: OPT (TIME) is fn effect, and the compiler 
can match the data list with the format list. 



Figure 9.10. Choice of subroutines for edit directed I/O 



2. A call to a compiler-generated 
subroutine to check whether a new 
record is reguired, and if so to call 
a library module to transmit a record 
by making a call to the transmitter. 

The SIOCB is completed with source or 
target DEDs and the addresses of the 
source and the target or their 
locators. 

3. A call to a conversion module or 
conversion director, or a compiled- 
code conversion using the information 
set up in the SIOCB. 

4. A further call to a compiler-generated 
subroutine, to update the buffer 
control fields, and free any 
intermediate workspace if spanning was 
involved. 

This seguence is illustrated in the 
annotated flowchart in figure 9.11. Figure 
9.12 shows the code generated for a GET 
EDIT statement. 



for the control format item, to one of the 
control format modules. There are four 
modules: 

1. IBMDSPL: library routine for SKIP, 
PAGE, and LINE formats and options. 

2. IBMDSXC: library routine for X and 
COLUMN formats. 

3. IELCGOC: compiler-generated 
subroutine for X output items that do 
not span a record boundary. 

4. IELCGIA: compiler-generated 
subroutine for X input items that do 
not span a record boundary. (This 
module also has other functions; see 
the section "Compiler-generated 
Director Routines" near the end of 
this chapter.) 



Matching and Non-Matching Data., and 
Format Lists 



Handling Control Format Items 



Control format items are implemented by 
passing the SIOCB, which contains the FED 



In the majority of edit-directed 
statements, the data and format lists can 
be matched during compilation, since the 
programmer requires conversions for 
specific variables. However, it is 
possible to write statements which, because 
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PUT EDIT (B)(A); 

FLOW DIAGRAM 



FLOW DIAGRAM 



O 

XT 
P> 

<+ 

CD 

n 



Stepl 
Compiled code 




Place address of 
variable, its DED, 
& DED generated 
from format item , 
inSIOCB 



Step 3 
Compiled code 




LA 


9,60(0, 4) 


ST 


9,848(0, 3) 


MVI 


77(4), X'20' 


LA 


1,844(0, 3) 


L 


15.A..IBMBSI0A 


BALR 


14,15 



Pick up address of SIOCB 
Place in parameter list 
Set "edit output" flag 
Point R1 at param. list 
Branch to initialization 
routine 



Carry out 
conversion either 
in - line or by 
calling library module 



Step 5 

Compiled code 
or conversion 
routine 



Test if file is open, and open if necessary, calling 
transmitter to locate record. 
Place address of ONCA and FCB in the SIOCB. 
Check statement validity. 



Call 
IELCGOB 



LA 2,60(ft 4) 

LA 14, B 

ST 14,0(0, 1) 

L 14,76(0, 3) 

L 7,A. ..IELCG0A 

BALR 6,7 



Point R1 at SIOCB 
Pick up address of B 
Place in SIOCB 
Pick up DED 
Branch to compiler - 
generated subroutine 




Step 6 
IELCGOB 



CalllBMBSEOA 
Call transmitter 
and free VDA 



Update F REM, 
FCB A, and FCNT 



Clear 'VDA' flag 
and IBMDSED 
flag 



Return to 
compiled code 



Acquire VDA for item if necessary. 

Either if there is no room in current record, or, 

if the converted item will span the record boundary. 



Continue from 
STEP 3 with next 
item, if any 



Step 7 
Compiled code 



J. 


15.A..IBMBCHFH I 


BALR 


14,15 | 


L 


7,A.. IELCGOB 


BALR 


v 



Call conversion routine 



Call compiler - generated 
director module 



Update buffer control fields 
Handle housekeeping 



Continue as necessary 



c 

o 
c 
f+ 

a 



Figure 9.11. Edit directed output statement with matching data and format lists 



PL/I statement: 


GET EDIT (A 


* STATEMENT NUMBER 3 


0000 7A 


41 


90 


4 


010 


00007E 


50 


90 


3 


060 


000082 


96 


80 


3 


060 


000086 


92 


24 


4 


021 


00008 A 


41 


00 


3 


050 


00008E 


50 


00 


4 


023 


000092 


41 


10 


3 


05C 


000096 


58 


FO 


3 


030 


00009A 


5 


EF 






00009C 


41 


EO 





0A8 


0000A0 


41 


FO 


3 


040 


O000A4 


41 


10 


4 


010 


0000A8 


50 


10 


4 


008 


OOOOAC 


90 


EF 


1 


008 


000060 


41 


EO 


3 


044 


000084 


58 


70 


3 


OOC 


000088 


05 


6 7 






00008A 


58 


FO 


3 


02C 


OOOOBE 


05 


EF 






OOOOCO 


5 8 


70 


3 


010 


0000C4 


05 


67 






0000C6 


41 


EO 


3 


04A 


OOOOCA 


58 


10 


4 


008 


OOOOCE 


58 


70 


3 


OOC 


000002 


05 


67 






0000D4 


41 


EO 


D 


OAC 


000008 


50 


EO 


1 


008 


OOOODC 


41 


EO 


3 


044 


OOOOEO 


58 


70 


3 


OOC 


0000E4 


05 


67 






0000E6 


58 


FO 


3 


02C 


OOOOEA 


05 


EF 






OOOOEC 


58 


70 


3 


010 


OOOOFO 


05 


67 






0000F2 











CL.2 



LA 


9,16<0,4> 


ST 


9,96(0,3) 


01 


96(3),X»80» 


MV1 


33I4),X«24« 


LA 


0,80(0,3) 


ST 


0,40<0,41 


LA 


1,92(0,31 


L 


15,A..IBMBSIIA 


BALR 


14,15 


LA 


14, A 


LA 


15, DEO.. A 


LA 


1,16(0,4) 


ST 


1,8(0,4) 


STM 


14,15,8(1) 


LA 


14,68(0,3) 


L 


7,A..IELCGIA 


BALR 


6,7 


L 


15,A..IBMBSFIA 


BALR 


14,15 


L 


7,A..IELCGIB 


BALR 


6,7 


LA 


14,74(0,3) 


L 


1,8(0,4) 


L 


7,A«.IELCG1A 


BALR 


6,7 


LA 


14, B 


ST 


14,8(0,1) 


LA 


14,68(0,3) 


k 


7,A..IELCG1A 


BALR 


6,7 


L 


15,A..IBMBSFIA 


BALR 


14,15 


L 


7,A..IELCGIB 


BALR 


6,7 


EQU 


* 



Pick up address of SIOCB 

Store in parameter list 

Mark end of parameter list 

Set 'edit input flag 

Set up abnormal locate return address (CL 2) 

Store in SIOCB 

Point Rl at parameter list 

Call stream I/O initialization routine 

Pick up address of source 

Pick up address of source DED 

Point Rl at SIOCB 

Save A(SIOCB) in temporary storage 

Store A(target) , A(target DED) in SI OCB 

Point R14 at FED 

Call compiler generated subroutine 
Call conversion director 
Call compiler generated subroutine 
Pick up FED of format item 

Call compiler generated subroutine 

Pick up address of second item 
Store in SIOCB 
Point R14 at FED 

Call compiler generated subroutine 

Call conversion director 

Call compiler generated subroutine 
Abnormal-! oca te return address 



'igure 9.12. Typical code generated for a GET EDIT statement 



of iteration factors, cannot be matched at 
compile time. For example, in the 
statement: 

PUT EDIT (A,B,C) (N(F(3)) ,X(10)) ; 

it is impossible to know at which point the 
ten-character space indicated by "X(10)" 
will be reguired, without knowing the value 
of N. If the statement had been 

POT EDIT (A,B,C) (F(3) ,X(10)) ; 

the code would be compiled in the order: 
handle the conversion of a variable, handle 
an X item, handle the conversion of a 
variable, etc., until the data list was 
exhausted. However, as it is not known at 
which point the X items will be reguired in 
the unmatched statement, it is impossible 
to compile seguential code to handle the 
statement. Consequently, the code for each 
item is compiled separately, and branches 
are made between the two types of code as 
the values of the repetition factor 
indicates. In the example above, the 
branches would be made when the F item had 



been executed N times, and when the X item 
had been executed once. 

The code seguences used for matching and 
non-matching data and format lists are 
shown in figure 9.13. 



Choice of Initialization Routines 



Three initialization routines are available 
for stream I/O using the FILE option. (The 
module for use with the STRING option is 
described later in the chapter.) The 
initialization routines are: 

IBMDSII - input only 

IBMDSIL - input and output, provided 

the COPY option is not used 
IBMDSIO - output only 

IBMDSIL has space saving advantages when 
either input or input and output are used 
in a program. If only output is used, 
IBMDSIO is the most economical module. 
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MATCHING LISTS 

PUT EDIT (I, NAME, ACT. NO) 

(F (3),X (3), A (15), X (3), P'ZZZ9'); 



HANDLE 
CONVERSION 
OF I 



HANDLE 
XITEM 



HANDLE 
CONVERSION 
OF NAME 



HANDLE 
XITEM 



HANDLE 

CONVERSION 

OF 

ACT - NO 



UNMATCHING LISTS 

PUT EDIT (AB, C, D) ((N) F (3), SKIP, A (4)); 



NO 



HANDLE 

CONVERSION 

F(3) 



YES 



HANDLE 

CONVERSION 

A(4) 



YES 




YES 





Figure 9.13. Code sequences for matching and non-matching data and format lists 
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Compiled code calls these modules as 
follows. 

IBMDSIL is used when both stream input 
and stream output are used in one program 
and the COPY option is not used for the 
input. 

IBMDSII is used when input with the COPY 
option is used in the program. 

IBMDSIO is used when only output is 
reguired, or when both input and output are 
reguired and the input uses the COPY 
option. 

The autolink feature of the DOS linkage 
editor prevents duplicate modules being 
incorporated into one program. To allow 
the choice of modules to be made by the 
linkage editor, IBMDSII contains additional 
entry points with the same names as those 
in IBMDSIL. Similary, IBMDSIL contains 
entry points with the same names as those 
in IBMDSIO. (The autolink feature resolves 
external references alphabetically. Thus 
if there is a reference to IBMDSII, any 
references to IBMDSIL entry points will be 
resolved to the entry points in IBMDSII. 
Similarly, any references to IBMDSIO can be 
resolved in IBMDSIL.) 



Handling Format Options 



Format options are handled by a call to the 
appropriate entry point of the 
initialization routine. 

The initializing module calls the 
formatting module IBMDSPL to carry out the 
formatting. 



specify the format of the input in the data 
stream. Conseguently the compiler must 
allow for any valid input form. Modules to 
handle the necessary conversions must, 
therefore, be included in the object 
module. This frequently results in a number 
of lengthy modules being link edited but 
never used. 

To overcome this problem, the compiler 
option LIMSCONV can be used. LIMSCONV 
specifies that the input stream will not 
contain items whose format would require 
the conversions shown below. 

Source (input stream). Targ et (va r iable ) 



arithmetic constant 
bit string constant 
binary constant 



string 

arithmetic 

arithmetic 



The occurrence of input that would cause 
these conditions results in the raising of 
the CONVERSION condition. 

When the LIMSCONV option is in force, 
the compiler does not generate external 
references for the modules that would 
handle the prohibited conversions. This 
results in considerable space savings. 
Compiled code differs when LIMSCONV is in 
force, in that calls are made to different 
director modules. IBMDSLJ is called for 
list-directed statements, and IBMDSDJ for 
data-directed statements. The list- 
directed director module, IBMDSLJ, contains 
code to check for the prohibited 
conversions and raise the CONVERSION 
condition if necessary. The data-directed 
module, IBMDSDJ, is exactly the same as the 
normal director module, IBMDSDI, except 
that it calls IBMDSLJ and not IBMDSLI. 
(Figure 9.8 shows how, in data-directed 
I/O, the list-directed director module is 
called to handle the conversions.) 



Input and Output of Complete Arrays 



When transmitting complete arrays, it is 
uneconomical for a return to be made to 
compiled code after each item has been 
handled. Accordingly, the list- and data- 
directed director modules have a facility 
that enables them to handle complete 
arrays. The modules access the array 
multipliers, and handle the indexing from 
information held in the array 
descriptors. For edit-directed I/O, each 
element is handled separately. 



PL/ 1 Conditions in Stream I/O 



The following errors and PL/I conditions 
are particularly relevant to the 
implementation of stream I/O: TRANSMIT, 
CONVERSION, NAME (data-directed only) , 
ENDFILE, and unexpected end of file. 
Unexpected end of file occurs when the end 
of file is reached in the middle of an 
input item. Other conditions that occur 
present no special problems. 



Effects of the LIMSCONV Option 



TRANSMIT Condition 



GET LIST and GET DATA statements do not 



The rules for raising the TRANSMIT 
condition in stream I/O are that the 
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condition shall be raised after the 
assignment of the potentially incorrect 
data item. Thus TRANSMIT can be raised on 
input for a data item even though the 
transmitter has not been called for the 
statement involved. 

When the TRANSMIT condition is detected 
by the LIOCS routines, control returns to 
the error routine in the transmitter, which 
sets a flag in the FCB indicating a 
transmission error. The director module 
inspects this flag, and, if it is set, sets 
a flag in the SIOCB. For input, TRANSMIT 
is raised for every item that is taken from 
a record in the block with which the 
transmission error was associated. 
TRANSMIT is raised after the potentially 
incorrect value has been assigned. For 
output, TRANSMIT is raised by the 
transmitter immediately it occurs. 

A special entry point, IBMBSEIT, is used 
by the compiler-generated subroutines to 
raise the TRANSMIT condition. When called 
by this entry point, the module calls the 
error handler with the appropriate error 
code for the TRANSMIT condition. 



ENDFILE Condition and Unexpected End of 
File 



End of file is detected by the LIOCS 
routines, which then enter the EOFADDR 
routine in the transmitter. This routine 
sets a flag in the FCB. On return to the 
director modules, the flag is inspected 
and, depending on the situation in which 
the transmitter was called, ENDFILE or 
unexpected end of file is raised by calling 
the error handler, with the appropriate 
error code. 

For unexpected end of file, the ERROR 
condition is always raised as soon as the 
end of file is detected. ENDFILE, in the 
case of list- and data-directed I/O, is not 
raised until a further attempt is made to 
read the input file. 



Built-in Functions in Stream I/O 



The built-in functions that are relevant to 
stream I/O are COUNT, DATAFIELD, ONCHAR, 
and ONSOURCE. 



CONVERSION Condition 



The CONVERSION condition is detected by the 
conversion modules in the PL/I library. 
(Conversions that could cause the 
CONVERSION condition are not handled in- 
line except where "NOCONVERSION" is 
specified.) CONVERSION is raised by calling 
a special library module, IBMDSCV. This 
module analyzes the type of conversion 
error, and calls the error handler with an 
appropriate error code. The module also 
saves the field that caused the conversion; 
it is necessary to do so, because the field 
could be lost if an on-unit was entered and 
another GET statement executed which 
resulted in a new record being acguired. 



ONCHAR and ONSOURCE are dealt with in 
chapter 10, under the heading "Raising the 
CONVERSION Condition." 

The COUNT built-in function is handled 
by the director routines. A count of 
transmitted items is kept in the FCB; the 
number is updated after every transmission 
to or from a PL/I variable. 

The DATAFIELD built-in function is 
handled by the director routine, which 
places the address of a string locator 
descriptor for the data in the ONCA. The 
offending field is first moved to a 
workspace area, as the buffer may get lost 
if further stream I/O operations take place 
in an on-unit. 



COPY Option 



NAME Condition 



The NAME condition can occur only in data- 
directed input. It is raised by the data- 
directed director module when it cannot 
find a symbol table to match the name read 
in. DATAFIELD is set up, and the file 
positioned for the next read, before 
calling the error handler, with the 
appropriate error code 



Implementation of the COPY option involves 
the use of a pointer, FCPM, in the FCB. 
FCPM points to the start of the data that 
is to be copied. Use is also made of the 
buffer control pointer, FCBA, to point 
immediately beyond the end of the data that 
is to be copied. At the end of the GET 
statement, or when further processing will 
result in the data to be copied no longer 
being held between FCPM and FCBA (for 
example when the transmitter is being 
called to acquire a new record) , the copy 
module IBMDSCP is called. IBMDSCP moves 
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GET LIST FILE (SYSIN) (STRING1) 
COPYFILE(A): 



GET LIST FILE (SYSIN) (STRING2) 
COPY FILE (A); 



GET LIST FILE (SYSIN) (STRING3) 
COPY FILE (B); 



FnPM 
















pointer for start of COPY data 






' 


' 




■ 


: 




'DATA FOR COPYING ONTO' 


'FILE 




NAMED A' 


'DATA FOR COPYING ONTO FILE B' 




i 










i 








FCBA 
















pointer fo 



Data is transmitted to the copy file at the end of each statement and at those 
times when it can no longer be held between the pointers FCBA and FCPM. 
In the example above this will be at the end of each GET statement and at 
the end of the first record. 



Figure 9.14. Use of FCBA and FCPM in copy option implementation 



the data into the buffer being used by the 
copy file, and then calls the transmitter 
to transmit the data. 



4. By the initialization routine, IBMDSII 
every time a GET statement is to be 
executed. 



The data to be copied is normally held 
between FCPM, which is initialized for a 
statement with the COPY option, and FCBA, 
which is updated with every input to point 
to the next position in the buffer from 
which data will be acquired. This is 
illustrated in figure 9.14. 

When execution of a GET statement with 
the COPY option is begun, the flag FCOP in 
the FCB is set, and the address of the FCB 
for the copy file is placed in the FCB of 
the input file to which the statement 
refers. 

To ensure that no data is lost, the copy 
flag, FCOP, is tested in the following 
situations: 

1. By the input transmitter, before a new 
record is acquired. 

2. By the stream I/O initialization/ 
termination routine, IBMDSII, after 
the completion of a GET statement with 
the COPY option. 

3. By the close routine, when the input 
file is being closed. 



If the copy flag is on, a call is made to 
the copy module, which transmits the data 
directly to the copy file, calling a 
suitable PL/I output transmitter. The copy 
flag is turned off after calling IBMDSCP in 
situations 2, 3, and 4 above. 



STRING Option 



Since the stream I/O director modules and 
conversion routines are primarily concerned 
with moving data in main storage, they are 
used to implement the STRING option as well 
as normal stream I/O. However, as the same 
modules are used, something must be done to 
prevent calls to a transmitter. It is 
achieved by having a special STRING module, 
IBMDSIS, that sets up a dummy FCB 
containing addresses which result in 
control being passed to suitable code when 
an attempt is made to call the transmitter. 

Compiled code passes the string 
initialization module an extended SIOCB in 
which the dummy FCB is set up. The buffer 
control fields FCBA and FREM in the dummy 
FCB are set up as if the string were a 
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record. The address that would hold the 
transmitter in the dummy PCB is set up to 
point to fields that will result in the 
correct action being taken if an attempt is 
made to read or write beyond the end of the 
string, or if a transmitter call is made. 

when an attempt is made to call the 
transmitter for a PUT statement, the 
address in the transmitter field will have 
been initialized to point to the error 
handler. As register 1 will have been 
pointed to the head of the FCB by the 
caller, the error code for exceeding string 
size is placed at the head of the FCB, and 
the correct error is automatically raised 
when the branch is made. 

When an attempt is made to call a 
transmitter for a GET STRING statement, the 
address in the transmitter field is the 
address of code set up in the dummy FCB 
that sets the end-of-file flag and returns 
to the caller. 

As far as the caller is concerned, 
attempting to read beyond the end of the 
string is eguivalent to finding an end-of- 
file mark in stream I/O statements. Where 
the ENDFILE condition or unexpected end-of- 
file would be raised for a stream file, the 
ERROR condition is raised, and a 'GET 
STRING SIZE EXCEEDED' message is issued. 



Summary of Subroutines Used 

This section gives a summary of the 
subroutines used in the implementation of 
stream-oriented input/output. Detailed 
descriptions of the library modules are 
given in the relevant program logic 
manuals. 

Nine different types of subroutine are 
used in stream I/O. They are: 

1. Initializing modules 

2. Director modules 

3. Transmitter modules 

4. Formatting modules 

5. Conversion modules 

6. External conversion director modules 

7. The conversion fix-up module (IBMDSCV) 

8. The copy module (IBMDSCP) 

9. The string module (IBMDSIS) 

Conversion modules are described in chapter 
10 of this manual. The other types of 
module are dealt with below. 



INITIALIZING MODULES 



Completing String-Handling Operations 



In certain circumstances a further call is 
made to the string routine IBMDSIS, to 
complete the operation. 

For ^out put into a fixed-length string, 
the routine is called, after the first 
assignment only, to blank out any remaining 
bytes in the string. For varying strings, 
a call is made after every assignment to 
update the current length of the string. 

For_ inpu t, for varying strings only, the 
routine is called to update the string 
information held in the dummy FCB, as this 
information may have been changed by an 
assignment to the string. 

The need to make a further call to 
IBMDSIS is flagged in the SIOCB when 
IBMDSIS is first called in connection with 
any particular statement. The library 
director routines and the compiler- 
generated subroutines test this flag, and 
call IBMDSIS if necessary. 



Initializing modules initialize the stream 
I/O statement. There are two of these 
modules: 

IBMDSII - input initializer 

IBMDSIO - output initializer 

IBMDSII and IBMDSIO are described earlier 
in this chapter. 



DIRECTOR MODULES 



Librar y Direc t or Routine s 



IBMDSLI - list-directed input 

Entry point A: element item 
Entry point B: complete array 

IBMDSLJ - list-directed input with LIMSCONV 

Entry Point A: element item 
Entry Point B: complete array 
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IBMDSLO - list-directed output 

Entry point A: element item 
Entry point B: complete array 

IBMDSDI - data-directed input 

Entry point A: with data list 
Entry point B: all known variables 

IBMDSDJ - data directed input with LIMSCONV 



Entry 
Entry 

IBKDSDO - 

Entry 

Entry 
Entry 



Entry 
Entry 



Point A: with data list 
Point B: all known variables 

• data-directed output 

point A 



point 
point 



point 
point 



B: 
C: 



D: 
T: 



element variables and 

whole arrays 

single array elements 

all known variables and 

SIGNAL CHECK when CHECK 

without a check list is 

enabled. 

CHECK output 

output a final semicolon 



Modules used with Compile r-Generated 
Subroutines 



IBMDSEI - edit-directed input 

Entry point A: housekeeping for input 
item spanning a record 
boundary. 

Entry point T: raise TRANSMIT for input 
item 

IBMDSEO - edit-directed output 



Modules for Complete Li brary Cont rol of 
Edit- Directed I/O of a S ingle Item 



IBMBSEHB: X format output 

1BMBSXCC: COLUMN format input 

IBMBSXCD: COLUMN format output 

IBMBSEHC: COLUMN format output 

IBMDSEH - Used when only output is required 
in a program, and there are no complex 
items. 

Entry points: 

IBMBSEHA: Edit-directed output of a 

data item 
IBMBSEHB: X format output 
IBMBSEHC: COLUMN format output 



Compiler-Generated Director Routines 



For input: 

IELCGIA - provides the address of the 

source of an edit-directed data 
or X-format item. 

IELCGIB - completes the transmission of an 
edit-directed data item, by 
freeing a VDA if one was used, 
updating the COUNT built-in 
function value, and calling 
IBMBSEIT if TRANSMIT has been 
raised. 

For output: 

IELCGOA - provides the address of the 

target of an edit-directed data 
item. 

IELCGOB - completes the transmission of an 
edit-directed data item, updating 
the buffer items in the FCB, 
counting the data item, and 
freeing a VDA if one was used. 



IBM DSE D - Used when complex data or format 
items appear in the program. 

Entry point A: input 
Entry point B: output 

IBMDSEE - Used when edit-directed input or 
edit-directed input and output are reguired 
in the same program, provided there are no 
complex items in the program. 

Entry points: 

IBMBSEEA: Edit-directed input of a data 

item 
IBMBSEHA: Edit-directed output of a 

data item 
IBMBSXCA: X format input 
IBMBSXCB: X format output 



TRANSMITTER MODULES 



The actual movement of the data between the 
external medium and the buffer area is 
carried out by a series of seven 
transmitter modules, which interface with 
the LIOCS routines of DOS data management. 
These modules essentially complete the 
setting up of the DTF, and issue the data 
management GET and PUT macro instructions, 
thus reading or writing one record. 

One module is used for input, six for 
output. The\output modules are divided into 
two groups: one group for PL/I print 
files, the other for all other output 
files. Both output module groups contain 
three modules: one for F-format records, 
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one for V-format records, and one for 0- 
format records. All modules interface with 
the queued sequential access method. 

The following transmitters are used: 

IBMDSTI - input transmitter 

IBMDSOF - output transmitter for F-format 
records 

IBMDSOV - output transmitter for V-format 
records 

IBMDSOU - output transmitter for D-format 
records 

IBMDSTF - print transmitter for F-format 
records 

IBMDSTV - print transmitter for V-format 
records 

IBMDSTU - print transmitter for D-format 
records 

The modules IBMDSTI (stream input) and 
IBMDSTF (stream output for F-format print 
files) are held in the resident library and 
are link-edited. Ml other transmitter 
modules are held in the transient library 
and loaded durinq file opening. 



FORMATTING MODULES 



Formatting modules control the position of 
the data on the external medium. There are 
three formattinq modules: two library 
subroutines, and one compiler-qenerated 
subroutine. 



Entry point C: SKIP option or format 
item 

IBMDSXC - X and COLUMN format items 



Lib rary Subroutin es 



IBMDSPL - PAGE, LINE, and SKIP format items 
and options 

Entry point A: PAGE option or format 

item 
Entry point B: LINE option or format 

item 



Entry point A: 
Entry point B: 
Entry point C: 
Entry point D: 



X format input 
X format output 
COLUMN format input 
COLUMN format output 



Com piler-Generated Subroutine 



IELCGOC - X i terns, in edit-directed output, 
that do not span a record 
boundary. 



EXTERNAL CONVERSION DIRECTOR MODULES 



The followinq external conversion director 
routines are used exclusively in edit- 
directed I/O: 

IBMBSAI - input A, B, and P character 

formats 
IBMBSAO - output A, B, and P character 

formats 
IBMBSCI - input C format 
IBMBSCO - output C format 
IBMBSFI - input F and E formats 
IBMBSFO - output F and E formats 
IBMBSPI - input P format arithmetic 
IBMBSPO - output P format arithmetic 



MISCELLANEOUS MODULES 

The other subroutines used in stream I/O 
are: 

IBMDSCP - the copy module 

IBMDSIS - the strinq module 

IBMDSCV - the conversion fix-up module 

IBMDSMW - module for calculatinq 

output format widths not 
specified in program 
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Chapter 10: Data Conversion 



Note on Terminology 



In this chapter, the terms source and 
targ et are used when referring to transfer 
of data. The source is the point from 
which the data is taken; the ta rget is the 
point to which it is moved, possibly in a 
converted format. 

The PL/I language specifies situations 
in which conversion of data types will be 
carried out. These include the execution 
of stream I/O and assignment statements, 
and the evaluation of expressions that 
include different types of data. The large 
number of data types allowed in the PL/I 
language means that some 170 types of 
conversion are possible. How these 
conversions are handled by the PL/I 
Optimizing Compiler depends, to some 
extent, on the optimization specified for 
the program. 

If no optimization is specified, all 
except simple conversions are carried out 
by calls to the library conversion package. 
If the program is being optimized, all 
possible conversions are done in-line. 

This chapter describes the library 
conversion package and explains how in-line 
conversions are handled. It concludes with 
a description of how the CONVERSION 
condition is raised. 

Before conversions can be understood, 
knowledge of the way in which data types 
are held is necessary. This is summarized 
in figure 10.1. 



The Library Conversion Package 



The library conversion package consists of 
26 modules and is capable of handling all 
the conversions that are allowed in the DOS 
PL/I Optimizing Compiler implementation of 
the PL/I language. All but seven of the 
modules convert data from one data type to 
another. As there are approximately 170 
possible conversions and only 19 conversion 
modules, many conversions are done by using 
a series of modules. For instance, to 
convert from fixed-decimal to bit-string 
involves an intermediate conversion to 
floating-point. The conversion package 
also contains five control and utility 
modules, and two modules used for stream 
I/O. 



Data attributes | Stored internally as 



BIT(n) 



BIT(n) VARYING 



CHARACTER (n) 



CHARACTER (n) 
VARYING 



FIXED DECIMAL (p,q) 



FIXED BINARY (p,q) 



FLOAT DECIMAL (p) 



FLOAT BINARY (p) 



PICTURE 



Aligned: one byte 
for each group of 
eight bits or part 
thereof. 

Unaligned: as many 
bits as are 
required, regardless 
of byte boundaries. 

As BIT (n) , with 
two-byte prefix 
containing current 
length of string. 

One byte per 
character. 

As CHARACTER (n) , 
with two-byte prefix 
containing current 
length of string. 

Packed decimal: 
Va-byte per digit, 
plus ^-/a-'-byte for 
sign. 

p <= 15: half word 
p>15: fullword 

p<=6: short 
floating-point 
p>6: long 
floating-point 

p<=21: short 
floating-point 
p>21: long 
floating-point 

One byte for each 
picture character 
(except K and V) 



Figure 10.1. 
types 



Internal forms of data 



The stream I/O modules move character and 
bit strings between the data management 
buffer and the PL/I variable when no 
conversion is necessary. 

A . full description of the routines in 
the library conversion package is given in 
the publication DOS P L/I Resi d en t Library: 
Program Logic. 
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The conversion paths followed for every 
conversion are known to the compiler, and 
ESD records are generated for all the 
modules that will be used. In certain 
cases, however, the data types involved are 
not known at compile time. Examples of 
this are data-directed and list-directed 
input, and edit-directed input or output 
when format and data lists cannot be 
matched. In such cases, the compiler 
generates ESD records for all conversion 
modules that could possibly be needed. 



will be a bit in the calling procedure's 
DSA, which is always set to zero. If the 
module is not the first to be called, the 
bit will be in library workspace and will 
have been set to one by the previous 
module. If the module is the first, library 
workspace will be acquired in the usual 
manner. If the module is not the first, a 
branch will be made around this code. 



ARGUMENTS PASSED TO THE CONVERSION 
ROUTINES 



SPECIFYING A CONVERSION PATH 



When a number of conversion modules need to 
be used for a certain conversion, it is 
necessary for there to be some control of 
the path taken after the first module has 
been entered. The method used is for each 
module to have a number of entry points. 
Each one is entered for a certain type of 
conversion, and each one implies the 
subsequent entry points to be invoked for 
that particular conversion. For instance, 
the module IBMBCE handles fixed-decimal to 
fixed-binary conversions. If the module is 
entered to carry out this conversion, entry 
point IBMBCEDX is called. However, if it 
is only an intermediate stage in a 
conversion from fixed-decimal to bit- 
string, the entry point IBMBCEDB will be 
called. When the conversion to floating- 
point is completed, the conversion to bit 
will be carried out by the module IBMBCR. 

In addition to the use of various entry 
points to specify the conversion path to be 
taken, there are two control modules to 
handle the conversion paths between 
character-string and arithmetic data. 



HOUSEKEEPING WHEN MORE THAN ONE MODULE 
IS USED 



When more than one conversion module is 
used in a conversion, a method of 
minimizing the housekeeping has been 
evolved. This avoids saving registers and 
acquiring workspace for each module 
entered. The same library workspace is 
used for all modules in a single conversion 
operation. The first module in the chain 
saves the registers and acquires workspace; 
the last module frees the workspace and 
restores the reqisters. 

A simple method is used to allow each 
module to test Whether or not it is the 
first to be called. A bit at a fixed 
offset from register 13 is tested. If the 
module is the first to be called, this bit 



Each conversi 
of parameters 
address of th 
addresses of 
descriptors) 
Arguments are 
register 1. 
constant that 
target is the 
result is to 



on routine has a standard set 
These consist of the 

e source and target, and the 

the DEDs (data element 

for the source and the target, 
passed in a list addressed by 

(The source is the variable or 
requires conversion; the 
area where the converted 

be placed.) 



The DEDs are used to describe the data 
type of the element. Those passed to the 
library conversion package are set up by 
compiled code in the constants pool. They 
are described in chapter 4 and fully mapped 
in appendix B. 



COMMUNICATION BETWEEN MODULES 



When the conversion path goes through a 
series of modules, the address of the final 
target must be retained until the last 
module is reached. 

Temporary targets are created for the 
intermediate results, and these are passed 
on as the source for the next module. When 
information is passed between two 
conversion modules, registers are normally 
used rather than a parameter list. 

Temporary DEDs are created for 
intermediate modules. These are set up in 
library workspace and are based on the 
original source DEDs. 

In some arithmetic conversions to 
string, precision data is passed through 
certain modules that do not themselves need 
such data. 



FREE DECIMAL FORMAT 



Because all floating-point data is in 
binary form, there is no direct 
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Conversion 


Comments and conditions 


Optimization 


Source 


Target 


SIZE 
disabled 


I SIZE 
enabled 






Fixed binary 


- 


- 


- 






Fixed decimal 


If either scale factor = and the 
other factor < 0, the optimization 
can be 'none 1 . 


time 


time 


Fixed 


binary 


Floating-point 


If source scale factor =0, the 
optimization can be 'none 1 (whether 
SIZE is enabled or not) . 


time 


time 






Bit string 


String must be fixed-length, aligned, 
and with length <2048. 


- 


not done 
in-line 






Character string 
or picture 


Source scale factor must be < 0. 
String must be fixed-length with 
length <256. Picture type 1, 2, or 3. 


time 


not done 
in-line 






Fixed binary 


If source and target scales have the 
same sign and are non-zero, the 
optimization (SIZE disabled) must be 
' time 1 . 




time 






Fixed decimal 


- 


- 


- 


Fixed 


decimal 


Floating-point 


Source precision must be <10. 


time 


time 






Bit string 


Source scale factor must be zero. 
String must be fixed-length, aligned, 
and with length <2048. 


■ — 


not done 
in-line 






Character string 


Source scale factor must be > 0. 
String must be fixed-length and 
length <256. 


time 


time 






Picture 


Picture type 1, 2, or 3. For 
picture types 1 and 2 with no sign, 
optimization can be 'none*. 


time 


not done 
in-line 






Fixed binary 


- 


time 


not done 
in-line 






Fixed decimal 


Target precision must be <9. 


time 


not done 
in-line 


Floating- 
point 


Floating-point 


Source and target may be single or 
double length. 


- 


- 






Bit string 


String must be fixed-length, aligned, 
and with length <2048. 


time 


not done 
in-line 



L - 1 

Figure 10.2. (Part 1 of 2) . Data conversions performed in-line 



representation of the PL/I floating-point 
decimal format. In order to simplify 
certain conversions, a simulated floating- 
point decimal format is employed by the 
optimizing compiler. This format is termed 
free decimal (sometimes known as backed 
inter me dia te d ecimal ) . The format of free 
decimal is a 17-digit packed decimal 



mantissa and a fullword binary exponent. 
Conversions to and from free decimal fori 
an integral part of the arithmetic 
conversion package. 
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r T 
| Conversion I I Optimization | 


| Source | Target | 1 SIZE | SIZE | 
|| | | disabled | enabled j 


I I Fixed binary | Source string must be fixed-length, | - |not donej 
I I j aligned, and with length <2048. j j in-line j 

|Bit string | Fixed decimal andjsource must be fixed- length, aligned,! time jnot donej 
I 1 j floating-point land with length <32. [ | in-line j 


| I Character string | String must be fixed-length with f — | — f 
I I I length <256. I | | 
I Picture | I III 

I | j Picture j Pictures must be identical. 1 - 1 - 1 


I I Fixed binary | Source precision must be <10. | time | not donej 
|| j || in-line | 

I j Fixed decimal jlf picture has a sign, the I - | not done| 
I I (optimization must be 'space*. | | | 
I Picture | j ill 
jtype 1 | | I j I 

j j Floating-point j Source precision must be <10. j time j j not donej 

I | Picture | Picture type 1, 2 or 3. I time |not donej 

II I j | in-line | 


I Locator | Locator | - | - | - j 


j Label | Label I - | - | - j 


JThe word "time" in the columns headed "Optimization" indicates that the conversion is j 
(done in-line only if optimization has been specified; "not done in-line" indicates | 
| that the conversion is done by library call. j 



Figure 10.2. (Part 2 of 2). Data conversions performed in-line 



In-Line Conversions 



The optimizing compiler generates in-line 
code for the more commonly used 
conversions. Eighteen basic types of 
conversion are handled in-line. Several of 
these basic types are used in conjunction, 
to enable a total of 28 conversions to be 
handled in-line. The circumstances in 
which in-line conversions are used are 
shown in figure 10.2. 



An example of the way in which a 
compiler conversion is used to convert from 
fixed-binary to fixed-decimal is given 
below. A list of the eighteen fundamental 
compiler conversions is given in figure 
10.3. 



Figures 10.2 and 10.3 use the terms 
"Picture type 1, 2, and 3". These picture 
types must contain only the following 
characters: 

V and 9 

Drifting or non-drifting characters $, + 

Zero suppression characters Z * 

Punctuation characters, . / B 

The types are defined as follows. 

Picture type 1 s Pictures of all 9s with 
(optionally) a V and a leading or trailing 
sign. For example: 

•99V999 1 , «99«, «S99V9», »99V+», 

'$999' 



140 



Conversion 
number 


Conversion 


2 


Fixed-binary to 
floating-point 


3 


Floating-point to 
fixed-binary 


4 


Fixed-decimal to 
floating-point 


5 


Floating-point to 
fixed-decimal 


6 


Fixed-binary to 
fixed-decimal 


7 


Fixed-decimal to 
fixed-binary 


8 


Character-string to 
fixed-decimal 


9 


Character-string to 
floating-point 


10 


Character-string to 
fixed-binary 


12 


Fixed-decimal to 
character- string 


14 


Bit-string to 
character-string 


15 


Fixed-binary to bit-string 


16 


Floating-point to bit-string 


17 


Bit-string to fixed-binary 


18 


Fixed-decimal to picture 
type 1 


19 


Fixed-decimal to picture 
type 2 


20 


Fixed-decimal to picture 
type 3 


21 


Picture type 1 to 
fixed-decimal 



Picture t ype 2: Pictures with zero 
suppression characters and (optionally) 
punctuation characters and a sign 
character. Also, type 1 pictures with 
punctuation characters. For example: 



Note: Conversions numbers 1, 11, and 13 
not used. 

L • ■- . J 



Figure 10.3. Fundamental in-line 
conversions 



«ZZZ«, «**/**9», 'ZZ9V.99* 
•$///99«, >9.9» 



•+ZZ.ZZZ' , 



Picture type 3: Pictures with drifting 
strings and (optionally) insertion 
characters and a sign character. For 
example: 



•$$$$«, «-, — 9«, •S/SS/S9' 
•+++9V.9' ,'$$$9-' 



Sometimes a picture conversion is not 
performed in-line even though the picture 
is one of the above types. This may be 
because: 



1. There is no overlap between the digit 
positions in the source and target. 
For example: 



DECIMAL (6,8) or DECIMAL (5, -3) to 
PIC '999V99' will not be performed 



2. The picture may have certain 

characteristics that make it difficult 
to handle in-line. For example: 



a. Punctuation between a drifting Z 
or a drifting * and the first 9 is 
not preceded by a V. For example: 



•ZZ.9.9 1 



Drifting or zero expression 
characters to the right of the 
decimal point. For example: 



•ZZV.ZZ', , ++V++« 
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BASIC CONVERSIONS 



Exam ple: Fixe d-Binary to Fixed-Decimal (Compiler Convers ion No. 6 ) 



The conversion is performed by converting from binary to decimal via a CVD instruction, 
with a scale-matching operation (to line up the decimal and binary points) either before 
or after the CVD (or occasionally both) . This scale-matching operation is done by shifts 
where possible but, depending on scales and precision, a decimal multiplier is sometimes 
used. 

DCL SOURCE FIXED BINAFY (31,9), 

TARGET FIXED DECIMAL (15,-6) ; 
TARGET=SOURCE; 



L 


E1 ( 


,SOURCE 




LTR 


R1, 


rR1 




BNM 


Compiler- 


label 


A 


F.1, 


r CONST 




Compiler- 


-label 


EQU * 


SRA 


R1< 


,9 




CVD 


R1, 


,KSP 




ZAP 


TARGET (8) 


,WSP(5) 



Load source in general register. 

Determine sign of source. 

Branch if >=0. 

Add a constant to negative source, rounding toward 
zero before subseguent divide (right shift) . 

Divide by source scale (2**9) . 

Convert to decimal in workspace. 

Transfer to target, at the same time dividing by 
10**6. 



MVN TARGET+7(1) ,WSP+7 



Transfer the sign. 



MULTIPLE CONVERSIONS 



The conversions listed in figure 10.3 can be regarded as fundamental types. A number of 
other conversions can be performed by using two fundamental conversions in series. These 
are shown in figure 10.4. 



HYBRID CONVERSION 



Raising the Conversion Condition 



Finally, there is one hybrid conversion 
that is carried out partially in-line. 
This is floating-point- to character-string, 
which reguires an interpretive routine to 
analyze the floating-point data (as 
distinct from the attributes, which all the 
others use) , in order to generate the 
correct scale factor. This is done by the 
library, because in-line code would use the 
same algorithm. However, partial 
optimization is carried out by setting up a 
character string of the correct length 
before calling the library, and then 
handling the subseguent string assignment 
in-line. 



The PL/I language specifies that when an 
invalid conversion is attempted on 
character-string data, the CONVERSION 
condition will be raised unless it has been 
disabled. 

When the CONVERSION condition has been 
raised, the language allows the program to 
access the invalid field or character by 
use of the ONSOURCE or ONCHAR built-in 
function. The language also stipulates 
that conversion should be attempted again 
if an on-unit is entered in which the 
ONSOURCE or ONCHAR pseudovariable is used 
to change the invalid field or character. 

Raising the CONVERSION condition 
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Conversion required 



| Compiler conversions used 



Fixed-decimal to bit-string 


No. 
No. 


7 
15 


Fixed-decimal to fixed-binary 
Fixed-binary to bit-string 


Floating-point to bit-string 


No. 
No. 


3 
15 


Floating-point to fixed-binary 
Fixed-binary to bit-string 


Bit-string to fixed-decimal 


No. 
NO. 


17 
6 


Bit-string to fixed-binary 
Fixed-binary to fixed-decimal 


Bit-string to floating-point 


NO. 
No. 


17 
2 


Bit-string to fixed-binary 
Fixed-binary to floating-point 


Character-string to bit-string 


No. 
NO. 


10 
15 


Character-string to fixed-binary 
Fixed-binary to bit-string 


Fixed-binary to character-string 


No. 
NO. 


6 
12 


Fixed-binary to fixed-decimal 
Fixed-decimal to character-string 


Fixed-binary to decimal picture 


NO. 
NO. 


6 
18 


Fixed-binary to fixed-decimal 
, 19, or 20 Fixed-decimal to picture 


Floating-point to decimal 
picture 


NO. 
NO. 


5 
18 


Floating-point to fixed-decimal 
, 19, or 20 Fixed-decimal to picture 


Decimal picture to fixed-binary 


No. 
No. 


21 
7 


Picture to fixed-decimal 
Fixed-decimal to fixed-binary 


Decimal picture to floating- 
point 


NO. 
NO. 


21 

4 


Picture to fixed-decimal 
Fixed-decimal to floating-point 


Decimal picture to decimal 
picture 


No. 
No. 


21 
■18, 


Picture to fixed-decimal 
, 19, or 20 Fixed-decimal to picture 



L 1 



Figure 10. 4. Multiple conversions 



involves a number of housekeeping problems, 
which are handled by a special conversion 
module, IBMBSCV. IBMBSCV is never called 
by compiled code, since conversions that 
could raise the CONVERSION condition are 
not attempted in-line unless the CONVERSION 
condition is disabled. IBMBSCV produces the 
correct error code for the error handler, 
IBMDERR, and looks after the housekeeping 
problems. 

The alternative to using a separate 
housekeeping module would be to place the 
code either in the error handler or in the 
various conversion modules. These solutions 
would result in a considerable overhead 



being carried either by all types of errors 
or by all correct conversions. The reason 
for the overhead lies principally in the 
facility offered by the language of using 
the ONSOURCE and ONCHAR built-in functions 
to access and optionally change the field 
causing the error, and subsequently 
reattempting the conversion on the changed 
field. 

Before any conversion in which the 
CONVERSION condition could be raised is 
attempted, the ONSOORCE field in the ONCA 
must be set up, and the address at which a 
reattempted conversion should begin must 
also be placed in the ONCA. 
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The code carrying out the conversion 
must then test the validity of the field to 
be converted and, if it is invalid, set the 
ONCHAR field in the ONCA to the first 
invalid character. The module IBMBSCV is 
then called to diagnose the conversion and 
produce the correct error code for the 
error handler. There are some twenty 
possible error codes associated with the 
CONVERSION condition. 

If the condition was raised during the 
execution of stream input, further action 
is necessary. This is because an on-unit 
may specify further input, and the buffer 
which contains the ONSOURCE field may be 
lost. For example the on-unit might be: 

ON CONVERSION BEGIN; 
ON CONVERSION SYSTEM; /* PREVENTS 
RECURSIVE ENTRY*/ 

GET LIST (KEYB) ; 

IF KEYB< 200 THEN ONCHAR =M»; 



ELSE ONCHAR = «9» ; 
END; 



If KEYB was in the next record, the source 
field that caused the conversion would be 
lost. To prevent this, a VDA is acguired 
in the LIFO stack, and the source field is 
stored in this VDA. The ONSOURCE and 
ONCHAR pointers are altered to point to the 
field in the VDA, and all further 
operations are carried out on this field. 

The NAB pointer associated with the 
block in which the interrupt occurred must 
then be altered so that it encompasses the 
VDA. The fact that the NAB pointer has 
been altered must be known in the block for 
a GOTO out of block to be handled. The 
reset-NAB bit is accordingly set to one in 
the relevant DSA. When these operations are 
complete, IBMBSCV calls the error-handling 
module IBMDERR. 
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Chapter 11: Miscellaneous Library Subroutines and System 
Interfaces 



In addition to employing the PL/I libraries 
for the functions described in previous 
chapters, the DOS PL/I Optimizing Compiler 
calls on a large number of computational 
and data-handling subroutines and on 
subroutines that provide interfaces with 
the operating system for such functions as 
TIME and DATE. These miscellaneous library 
calls are discussed in this chapter. The 
library subroutines themselves are fully 
described in the publications IBM 
Disk Operating System; PL/I Resident 
Library Prog ram Lo gic and I BM Di sk 
Operat ing Syst em: PL/I Transient 
Li br ary Pr ogr am Logic . 

This chapter is divided into two main 
sections: the first deals with the 
computational and data-handling 
subroutines, and the second with 
miscellaneous system interfaces. 



used in the computation of several of the 
trigonometrical functions. 

Arguments are passed to the arithmetic 
and mathematical subroutines either in 
registers or in a parameter list addressed 
from register 1. The use of registers 
results in faster execution, but allows 
less flexibility in use of the routines. 
All built-in functions, except the STRING 
built-in function, have their arguments 
passed in a list comprising the addresses 
of the source and target (and sometimes 
also the addresses of DEDs) . Where 
possible, other routines use registers. 
Computational routines are always carried 
out in floating-point unless otherwise 
indicated. This may involve conversion 
before calling the routine. 



Computational and Data-Handling 
Subroutines 



The computational and data-handling 
subroutines are used to handle all the 
mathematical built-in functions, the 
majority of arithmetic built-in functions, 
and a number of array-handling, structure- 
handling, and string-handling functions. 
The extent to which library calls are used 
depends on the level of optimization 
specified by the programmer, the type of 
data involved, and, for string functions, 
on whether S.TRINGRANGE and STRINGSIZE are 
enabled. 



ARITHMETIC AND MATHEMATICAL SUBROUTINES 



The compiler always uses library 
subroutines for mathematical functions. 
The use of compiled code in these 
circumstances is impracticable. Where 
possible, arithmetic functions are handled 
by in-line code. The circumstances in 
which library subroutines are used are 
listed in figure 11.1. 

Considerable use is made of chains of 
library modules to carry out the various 
functions. For example, the subroutines 
that handle complex arithmetic normally 
call on those that handle real values to 
process each part of a complex number; 
similarly, the sguare-roOt subroutine is 



ARRAY, STRING, AND STRUCTURE 
SUBROUTINES 



A number of array, string, and structure 
subroutines are included in the DOS PL/I 
Resident Library. These are used to carry 
out certain of the array and string built- 
in functions and a number of other 
operations. Where possible, in-line code is 
generated to carry out these functions. 
However, the enablement of STRINGSIZE, the 
use of unaligned bit strings, and the use 
of adjustable and certain varying-length 
strings will result in calls being made to 
the library sub-routines. 

The subroutines involved in these 
functions are shown in figure 11.2. Two of 
them, IBMBAIH and IBMBAMM, are concerned 
with the handling of data aggregates rather 
than with the execution of specific 
operations. They are discussed below. 



Indexi ng Interleaved Arr ays (IBMBAIH ) 



IBMBAIH is used to assist the other library 
array-handling subroutines to process 
multidimensional interleaved arrays. It is 
not called by compiled code. 

Interleaved arrays are arrays whose 
elements are not held contiguously in 
storage. They occur in arrays of 
structures. For example, the declaration: 
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Function 


Data type 


Module 


When used 














name 










REAL ARGUMENTS 


Short floating-point 


IBMBMXS 


When exponent 


is 


a 




Integer 


exponentiation 


variable 






Long floating-point 


IBMBMXL 


When exponent 


is 


a 


variable 


General 


exponentiation 


Short floating-point 
Long floating-point 


IBMBMYS 
IBMBMYK 


Always 
Always 








COMPLEX 


ARGUMENTS 


Short floating-point 


IBMBMXW 


When exponent 


is 


a 




Integer 


exponentiation 


variable 






Long floating-point 


IBMBMXY 


When exponent 


xs 


a 


variable 


General 


exponentiation 


Short floating-point 
Long floating-point 


IBMBMYX 
IBMBMYY 


Always 
Always 









L ; . J 

Figure 11.1. Arithmetic operations performed by library subroutines 



IBMBAAH I ALL and ANY built-in 
functions 

IBMBAIH | Indexer for interleaved 
arrays 

IBMBAMM | Structure mapping 

IBMBANM | STRING built-in function 

IBMBAPC | PROD built-in function 
(fixed-point integer) 

IBMBAPF | PROD built-in function 
(floating-point) 

IBMBAPM | STRING pseudo-variable 

IBMBASC | SUM built-in function 
(fixed-point) 

IBMBASF I SUM built-in function 
(floating-point) 

IBMBAYF | POLY built-in function 
(floating-point) 

IBMBBBA I AND and OR logical 

operations (aligned bit 
strings) 

IBMBBBC | Compare aligned bit strings 

IBMBBBN | Invert aligned bit string 
(NOT) 

Figure 11.2. (Part 1 of 2). Array, 

structure, and string subroutines 



146 



DCL 1 STRUCTURE (2) , 
2 A (2), 
2 B ; 

would result in successive storage 
locations being allocated to elements of A 
and B as follows: 

A(1,1),A(1,2),B(1),A(2,1),A(2,2),B(2) 

Both A and B are interleaved arrays. A is 
a two-dimensional array, the first row of 
which is separated from the second by an 
element of B. As can be seen, the elements 
of A are not contiguous, nor is there a 
fixed interval between their addresses. 



When IBMBAIH is called, it is passed the 
address of a work area in which to 
construct a table, the address of the array 
descriptor, and the number of dimensions in 
the array. Basically, IBMBAIH calculates 
the extent of each dimension and enters 
this information in the table; it then 
calculates the increments that must be 
added in order to step between elements 
that may be non-contiguous (see figure 
11.3). The information in the completed 
table is used by the calling module to 
address successive elements of the array 
using simple code. 



IBMBBCI | INDEX built-in function 

(character string) 
IBMBBCK | Concatenate character 

strings and REPEAT built-in 

function 

IBMBBCT | TRANSLATE built-in function 
(character string) 

IBMBBCV I VERIFY built-in function 
(character string) 

IBMBBGB | BOOL built-in function 

IBMBBGC | Compare unaligned bit 
strings 

IBMBBGF | Bit-string assignment 

(aligned, source and target) 

IBMBBGI | INDEX built-in function (bit 
string) 

IBMBBGK | Concatenate bit strings, 
REPEAT built-in function, 
and assign 

IBMBBGS | Produces SLD (SUBSTR 
built-in function) 

IBMBBGT | TRANSLATE built-in function 
(bit string) 

IBMBBGV | VERIFY built-in function 
(bit string) 



Figure 11.2. (Part 2 of 2). Array, 
structure, and string subroutines 



The interval between the addresses of 
elements of an interleaved array referred 
to by varying only the final subscript is 
always fixed, and these elements can be 
stepped through by using the last 
multiplier from the array descriptor. 
However, such groups of contiguous elements 
are not themselves necessarily contiguous. 



Structure Mapping ( IBMBAM M) 



Structures are normally ma 
compilation. However, cer 
that contain adjustable st 
cannot be mapped until the 
or bounds are known. Comp 
on the module IBMBAMM to c 
mapping. There are four e 



pped during 
tain structures 
rings or arrays 
actual lengths 
iled code calls 
arry out this 
ntry points: 



IBMBAMMA Compute length of structure. 

IBMBAMMB Map structure in PL/I manner. 

IBMBAMMC Map structure in COBOL manner 

(for interlanguage comunication 
or for files declared with the 
COBOL option) . 

IBMBAMMD Map structure declared with 
REFER option. 



Miscellaneous System Interfaces 



In addition to the system interface used 
for input and output, the PL/I Optimizing 
Compiler makes use of a number of other 
system facilities. These are for the 
DELAY, DISPLAY, and WAIT statements, the 
TIME and DATE built-in functions, and the 
sort/merge and checkpoint/restart built-in 
subroutines. 

Calls to these facilities are made 
through library subroutines held in the DOS 
PL/I Resident Library. These subroutines 
act as an interface, issuing any SVC calls 
that may be necessary, and handling 
housekeeping problems. The descriptions of 
the subroutines in this chapter are kept to 
a minimum except where the housekeeping 
problems are large and have a major effect 
on the contents of main storage. In these 
cases, background information is given and 
the various control blocks are explained, 
thus enabling the situation during 
execution to be understood. 
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Declaration 




DECLARE 


1 X(2), 




2 C, 




2 Y (2), 




3 Z (3), 




3 B; 



Storage 



c 






Z(1, 1, 1) 


M 3 f A 


Z (1, 1,2) 


I 
M 2 

1 




Z(1, 1,3) 




B 




Z(1,2, 1) 


M, 


Z(1,2, 2) 


1 




Z(1,2, 3) 




B 




C 


r 


Z(2, 1,1) 




Z(2, 1,2) 




Z(2, 1,3) 




B 




Z (2, 2, 1 ) 




Z (2, 2, 2) 




Z (2, 2, 3) 




B 





Z is a three-dimensional interleaved array, for which 

M., , M 2 , and M 3 = multipliers held in array descriptor (see chapter 4) 



lnc 1 and lnc 2 



intervals between addresses of successive elements of Z when subscripts 
for first and second dimensions, respectively, change 



Figure 11.3. Indexing interleaved arrays 
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The increment when the subscript for the ith dimension changes is computed 

Inc, = Mi - E i+1 *M i+1 + lnc i+1 

Where E i + 1 is the extent of the (i+1)th dimension. 

Increment table for array Z (as initialized by IBMBAIH) 


as follows: 
the extent of 






2 


subscript count 
extent of dimension 
increment 

subscript count 
extent of dimension 
increment 


2nd dimension S 




2 


._. { 


lnc 2 


2 


2 


Inc, 


No te: IBMBA IH returns th 
the 3rd dimension = 


e e 
3 


xtent of the nth dimi 
) 


?nsion in register 1. (In this example, 



The DOS macro instructions referred to 
below are described in IBM, Sy. st em/360 Disk 

Operating System; Supervisor a nd 

Ifl pgt/Qgt|)ut Macros. 



SETIME macro, points to the TECB. On 
completion of the wait, the time will have 
elapsed and control is returned to compiled 
code. 



TIME 



DISPLAY 



The PL/I TIME built-in function is 
implemented by issuing a GETIME macro 
instruction. This is done by the module 
IBMDJTT. 

On entry from compiled code, register 1 
points to the address of the character- 
string target. The module issues a GETIME 
macro instruction with the TD option, and 
the current time is returned as a character 
string of length nine in the form 
hhmmssttt. The GETIME macro, and 
conseguently this module, returns the time 
of day to the nearest 1/300 second. 



DATE 



The PL/I DATE built-in function is 
implemented by module IBMDJDT, which 
accesses the job's communications region to 
obtain the necessary data. 

On entry from compiled code, register 1 
points to the address of the date character 
string. The module accesses bytes - 7 of 
the communications region, which contain 
the data in the form ddmmyy if bit of the 
date-convention byte is 1, or in the form 
mmddyy if the bit is 0. The date is then 
translated using the appropriate translate 
table. The date is returned as a character 
string of length six in the form yymmdd. 



DELAY 



The PL/I DELAY statement is implemented 
using the SETIME and WAIT macro 
instructions, which are issued by module 
IBMDJDY. The SETIME macro instruction 
allows the interval time to be set only to 
an integral number of seconds; hence the 
delay is restricted to an integral number 
of seconds. On entry from compiled code, 
register 1 points to the number of 
milliseconds delay. The delay interval is 
rounded to the nearest second and a maximum 
interval of less than 55919 seconds set up. 
A SETIME macro is issued, specifying the 
interval and a timer event control block 
(TECB) name. A WAIT macro instruction is 
issued to delay execution for the reguired 
interval; register 1, unchanged by the 



The PL/I DISPLAY statement is implemented 
by two library modules, IBMDJDS and 
IBMDJDZ. IBMDJDZ handles display without 
the EVENT option; IBMDJDS handles display 
with the EVENT option. 



IBMDJDS DISPLAY with EVENT Option, 



DISPLAY without REPLY Option 



If no reply is reguested, the message is 
scanned and trailing blanks are removed. 
An EXCP macro instruction is issued, 
specifying a channel control block (CCB) 
that contains the address and length of the 
message. 



If a reply is requested 
scanned and trailing blank 
Three channel command word 
for the message and reply: 
put out the message, the s 
a standard message saying 
and the third to accept th 
macro instruction is issue 
option is not specified, a 
instruction is also issued 
to compiled code. 



, the message is 
s are removed, 
s (CCWs) are used 

the first to 
econd to put out 
"awaiting reply," 
e reply. An EXCP 
d; if the EVENT 
WAIT macro 

Return is made 



If the EVENT option is specified, the 
event variable is checked before the EXCP 
macro instruction is issued, to see if it 
is active. When the corresponding WAIT 
statement in compiled code is executed, 
IBMDJWT returns control to IBMBJDSB on 
completion of the event. 



IBMDJDZ - DISPLAY without the EVENT 
Option 



When IBMDJDZ is entered, the display string 
is scanned and trailing blanks are removed. 
If thepe is no REPLY option, an EXCP macro 
and a WAIT macro are issued to transmit the 
message to the console. The channel 
control block (CCB) used contains the 
address and length of the message. Return 
is then made to the caller. 

If there is a REPLY option, the EXCP and 
WAIT macros are issued as above. However, 
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the EXCP specifies a chain of three channel 
control blocks. The first channel control 
block is to transmit the display string, 
the second is to transmit a standard 
message to the operator stating that a 
reply is required, and the third is for the 
reply to the message. When the reply is 
recieved, return is made to the caller. 

If a unit check or exception occurs on 
the console, any reply string is blanked 
out and the EXCP and WAIT macros for the 
display or reply are reissued. The ERROR 
condition is raised if there is a zero 
length display with the REPLY option, or if 
the length of the string to accept the 
reply is zero. 



SORT/MERGE 



The PL/T programmer can make use of the DOS 
sort/merge facilities through a call to the 
built-in subroutine PLISRT. The method of 
using the facility is fully described in 
the publication IBM OperatingSystem: 
PL/I Optimizing Compiler Programmers' Guide 



The DOS sort/merg 
number of user exits 
conveniently thought 
programmer to write 
become included in t 
Two of these user ex 
PL/I programmer: us 
records to be set up 
the SORT routines; u 
records that have be 
to and processed by 



e program includes a 

that can be 

of as allowing the 
sections of code that 
he sort/merge routines, 
its can be used by the 
er exit 15 allows 

by PL/I and passed to 
ser exit 35 allows 
en sorted to be passed 
the PL/I program. 



Exits are not allowed in the PL/I 
language. To overcome this problem, code 
is inserted between the sort/merge modules 
and the PL/I routines. A bootstrap module, 
IBMDKST, is used, and this module acts as 
an interface between SORT and PL/I. The 
module retains the PL/I environment and 
restores it on return from sort/merge so 
that the PL/I exit-15 or exit-35 code can 
operate in a PL/I environment. Similarly, 
it restores the environment for SORT on 
return from the exit. 



Housek eep ing, Problems 



Various housekeeping problems occur in the 
user exit procedures, since there is no DSA 
chain through the SORT modules. 
Particularly difficult is the handling of a 
GOTO out of the exit procedure that passes 
control to a procedure on the same or 
higher level as the procedure that 
originally called the sort program. This 



action implicitly terminates SORT. 
However, SORT will not be terminated by 
standard PL/I action, since it does not 
function in the PL/I environment. 

The problems are overcome by setting up 
a chainback that includes a simulated DSA 
for the SORT routines. This DSA is 
specially flagged so that it can be 
recognised by the GOTO code. The chaining 
of save areas in shown in figure 11.4. 

An area of workspace is acquired by the 
bootstrap routine IBMDKST. This consists 
of one level of library workspace, a VDA of 
the correct size to hold two save areas, 
and a nine-word area of workspace. The 
second DSA is chained back to the first. 
(See figure 11.4.) 

If the SORT program is terminated by a 
GOTO out of the block that contains the 
PL/I exit program, the SORT routine has to 
be terminated before the GOTO can be 
completed. This is done by the GOTO 
routine looking for the SORT exit DSA 
(which is specially flagged) in the DSA 
chain. If one is found, a return code of 8 
is set up and return made to the SORT 
routine. This results in the termination 
of the SORT routine, and the GOTO can then 
be continued in the usual manner by 
following the DSA backchain through the 
bootstrap routine until the target DSA is 
reached. 

For handling on-units in the exit 
procedure, the DSA chain can be followed 
without reference to SORT. 



Restoration., of the .PL/I Environment on 
Exit from SORT 



When an exit is made from SORT, it is 
necessary to restore the PL/I environment. 
The method used is to have a section of 
code that restores the registers at the 
point to which SORT makes its exit. Use is 
made of the SORT exit table shown in figure 
11.4. As can be seen, which ever exit is 
taken, control passes to this code, which 
saves the registers passed by SORT and 
restores the registers of the bootstrap 
module IBMDKST, thus restoring the PL/I 
environment. The save area of the SORT 
bootstrap routine is addressed by means of 
an offset from the code that is being 
executed. This is possible because the 
SORT exit table and the register save area 
are both held in the same workspace at a 
fixed offset from each other. The code is 
not included in the bootstrap module, in 
order to preserve reentrancy. 
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I * 


Backchain 












^ 






^ 




" Backchain 




First save area: 
for SORT interface 
modu le 




* Exit table 






Backchain 




Second save area: 
for exit routine 
interface 




Work area for the 
interface routines 




Address of SORT 
save area 





























DSA for PL/I program 
requiring SORT facilities 



Sort bootstrap DSA on 
calling SORT 



Sort bootstrap DSA on 
calling exit routine 



PL/I exit procedure DSA 



Exit table 





NOP 





Entry point for E15 


BC 


15,12(15) 


Entry point for E35 


BC 


15,12(15) 




STM 


14,12,12(13) 




L 


2,28(15) 




LM 
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not used 

branch to exit code for E15 exit 
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save sort registers 
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restore bootstrap registers 

initialized address of routine 

address of first save area 



Figure 11.4. DSA chaining during execution of SORT 
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Summary of Work Done by the SORT Module 

Before calling the SORT program, IBMDKST: 

1. Obtains a VDA for two DSAs. 

2. Creates a parameter list suitable for 
SORT. 

3. Sets up addressability code for use 
after return from SORT. 

H. Sets the program check exit so that a 
program check results in entry being 
made to a section of the sort 
bootstrap. The sort bootstrap then 
determines the error, puts out a 
message to SYSPSINT indicating that a 
program check has occurred during the 
execution of SORT, and then terminates 
the program. 

On exit from the SORT program, the 
addressability code saves the registers of 
SORT and reestablishes the PL/I 
environment, and then branches to an entry 
point of IBMDKST, which: 

1. Resets the program-check exit so that 
control will pass to the PL/I error- 
handling routines. 

2. Sets up parameters for the PL/I exit 
routine from information passed by 
SORT. 

3. Calls the PL/I exit routine. 

Setting the return code in the PL/I exit 
program resets the parameters that IBMDKST 
passes to the SORT routines. (See figure 
11.5.) 



Storage.for SORT 



Storage for sort/merge workspace and the 
modules used is obtained in the LIFO stack. 
A VDA of the correct length is obtained by 
the bootstrap module. The length reguired 
must be specified in the arguments that are 
given in the call to PLISORT. 



CHECKPOINT/RESTART 



The PL/I Optimizing Compiler allows the 
programmer to make use of the system 
checkpoint/restart facilities by calling 
the built-in subroutine PLICKPT. This is 
implemented by a call to the resident- 
library subroutine IBMDKCP, which issues 
the CKPT macro instruction. 



Before the CKPT macro instruction is 
issued, two control blocks must be set up. 
One of these control blocks contains the 
names of all tape files that are open; it 
is used to reposition the tapes on restart. 
The other control block contains 
verification information for all disk files 
that are open; it is used to verify that 
the disk packs are on the same devices on 
restart as they were when the check-point 
was taken. The two control blocks are held 
in the workspace acguired for the module 
IBMDKCP. 

When a restart is made, control is 
passed to the module IBMDKCP at a fixed 
entry point. After carrying out necessary 
checks, control is then returned to the 
calling routine in the normal manner. 
Control is thus returned to the statement 
after the call to PLICKPT, and processing 
continues. 



WAIT 



The PL/I WAIT statement allows the 
programmer to specify that processing shall 
halt until a specified number of events are 
complete. In this implementation, an event 
can be associated with either a record I/O 
operation or a DISPLAY statement, or it can 
be an inactive event that is not associated 
with any operation. 

All information relating to an event is 
kept in an event variable. This is a 
control block of five words in length ; it 
is treated for storage allocation like any 
other PL/I variable. The event variable 
holds information on whether the event is 
associated with an operation and whether it 
is complete; it also records the status of 
the event (i.e., whether the associated 
operation was completed successfully or 
otherwise) . When an event is associated 
with an operation, it is said to be active ; 
otherwise, it is said to be inact ive . 

When the wait statement is used, the 
keyword WAIT is followed by a list of 
events that are to be waited on. A number 
can follow this list, indicating that only 
that number of events need be completed 
before processing can continue. Typical 
WAIT statements are: 

WAIT (EVENT1,EVENT2) ; 

WAIT (EVENT1,EVENT2) (1); 

For the first statement, both the events 
would have to be completed before 
processing could continue. For the second 
statement, processing would continue as 
soon as either of the events was complete. 
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Main procedure 




1 


' 




SORT 

bootstrap 

IBMDKST 




1 


P 




SORT 




1 


f 




Addressability code 


Ai 










1 


t 






SORT bootstrap 




1 




l 




PL/I exit routine 





Call SORT bootstrap 



Set program-check exit for SORT to code in SORT bootstrap. 
Arrange parameters for SORT. 
Store registers in first bootstrap DSA. 
Call SORT. 



Sort as instructed by parameters. 



Save registers in SORT save area. 
Restore registers for bootstrap. 
Branch to bootstrap. 



On entry from SORT 

Reset program-check exit 

for PL/I. 

Set up parameters for exit 

routine from information 

passed by SORT. 

Call exit routine. 



On entry from exit routine 

Reset program-check exit 
for return to SORT. 
Arrange parameters for SORT. 
Restore SORT registers. 
Return to SORT. 



Carry out processing — return to SORT bootstrap. 



Figure 11.5. Summary of action during use of SORT exit 
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is: 



WAITER: PROC OPTIONS (MAIN) ; 

ON TRANSMIT (A) CALL L; 
ON TRANSMIT (C) CALL L; 
ON TRANSMIT (X) CALL L; 



ON RECORD 
ON RECORD 
ON RECORD 
K=0; 
READ FILE 

(E1) ; 

READ FILE 

(E2) ; 



(A) 
(C) 
(X) 



CALL M; 
CALL M; 
CALL M; 



(A) INTO (E) EVENT 
(C) INTO (D) EVENT 



WAIT (E1,E2) ; 



IF K=1 THEN WAIT (E2) ; 



5 BOOTLE: WAIT (E3) ; 





L: 


PROC; 


6 




COMPLETION (E3) = M*B; 


7 




GO TO BOOTLE; 
END L; 




M: 


PROC; 


8 




COMPLETION (E3)=«1«B; 


9 




WAIT (E2) ; 


10 




K=1; 


11 




READ FILE(X) INTO(Y) EVENT 
(E2) ; 
END M; 

END WAITER; 



Figure 11.6. Example of WAIT 

implementation problems 



The WAIT statement implemented in any 
particular installation depends on whether 
or not that particular system supports the 
DOS data-management WAITM macro 
instruction. If it does not support this 
macro instruction, the full PL/I WAIT 
statement cannot be supported and the 
routine IBMGJWT will be included in the DOS 
PL/I Resident Library. If the WAITM macro 
instruction is supported, the full WAIT 
statement can be supported, and the module 
IBMDJWT will normally be included in the 
resident library, although it will be 
possible to specify the other module if the 
full WAIT facilities are not reguired. 

The difference between the two modules 



IBMGJWT Supports only waits on 
single events. 

IBMDJWT Supports waits on multiple 
events. 



Event Variables 



When storage is allocated for an event 
variable, the event variable is set 
inactive and incomplete. When the EVENT 
option is used to associate the event with 
an operation, the event variable is set 
active and incomplete. When a WAIT 
statement is executed and the operation 
associated with the event has been 
completed, the event variable is set 
inactive and complete. The status of the 
event is also set at this time, indicating 
whether or not the operation was 
successfully completed. 

The PL/I language allows the programmer 
to set complete or incomplete any inactive 
event, by use of the COMPLETION 
pseudovariable^ This sets the appropriate 
bit in the event variable. The completion 
status may be inspected by means of the 
COMPLETION built-in function. The PL/I 
language also allows the programmer to 
inspect and change the status of an event, 
by means of the STATUS built-in function 
and pseudovariable. 



WAIT Statement 



The WAIT statement is implemented by a call 
to the resident library routine IBMDJWT. 
This is passed a set of parameters 
consisting of the addresses of the event 
variables and the number of events that 
have to be completed. If the number of 
events that have to be completed is not 
specified, all the events in the list must 
be completed. 

The WAIT makes use of the DOS data- 
management WAITM and WAITF macro 
instructions. However, because of the 
differences between the facilities offered 
by the DOS system and the PL/I language, 
considerable housekeeping problems are 
involved for waits on more than one event. 
For waits on single events, the problems 
are small and are described at the end of 
this section. 

When a WAIT or associated macro 
instruction is issued to the DOS 
supervisor, the event is considered to be 
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complete when input/output transmission is 
finished. In PL/I, however, a WAIT 
statement is not considered complete until 
any error-handling activity caused by the 
operation which was being waited on is 
finished. The error handling may include 
entry into an on-unit, and further WAIT 
statements may be executed in the on-unit. 
This process can continue to any number of 
levels of interrupt. 

PL/I also allows the programmer direct 
control over the completion of an event by 
use of the COMPLETION pseudo-variable. 
Consequently, the PL/I programmer need not 
associate an event variable with an 
input/output operation, but can use it 
instead as a flag, setting the event 
complete at any point in the program. 



ructions 
pleted by 
ECB (event 
the DTF. 
indicated 
the event 
is carried 
and the 



WAIT or associated macro inst 
issued to the supervisor are com 
setting a completion bit in the 
control block) which is held in 
At the PL/I level, completion is 
by setting the completion bit in 
variable. Thus a WAIT operation 
on at two levels, the PL/I level 
system level. 



Housekeeping Problems 



The problems involved in implementing the 
WAIT statement may be illustated with 
examples from the skeleton program in 
figure 11.6. Four problems arise. They 
are: 

Proble m 1 : If an event being waited on in 
a multiple WAIT statement is completed in 
an on-unit entered while processing one of 
the other events in the statement, this 
must be made known to the first WAIT 
statement. Setting the event variable 
complete is not sufficient, because the 
event variable may be used again during the 
on-unit. Suppose that the RECORD condition 
is raised during the execution of the WAIT 
statement numbered 3 in figure 11.6, for 
the operation associated with event E1. 
The following then takes place: 

1. Control passes to procedure M. 

2. The statement WAIT(E2) is then 
encountered, and the program waits 
until event E2 is completed. When 
this occurs, the event variable is set 
complete and inactive. 

3. Event E2 is then used in a further I/O 
operation (statement 11), causing the 
event variable to be set active and 
incomplete. 



On return to the main program, there would 
be no way of determining from the event 
variable for E2 that the original event E2 
had been completed. The problem is solved 
by the use of control blocks called eve nt 
tables (EVTABs) . An EVTAB is set up by the 
wait module each time a WAIT statement is 
encountered; it contains entries for each 
incomplete event specified in the 
statement. The entries are termed EVTAB 
elements. Each element is chained to its 
corresponding event variable and contains a 
bit that can be set to indicate that the 
event has been completed. In the above 
example, therefore, EVTAB elements for E1 
and E2 are set up when the wait module is 
called at statement 3. When the on-unit is 
entered, the WAIT statement 9 causes a 
further EVTAB to be set up with an entry 
for E2. The event variable pointer is reset 
to address the latest EVTAB elements, and a 
field in this element is set to point to 
the previous EVTAB element for E2. When 
event E2 is completed (without causing any 
I/O conditions to be raised) , the event 
variable and each EVTAB element for E2 is 
set complete and inactive, and a bit in the 
event variable is set to indicate that the 
chain of EVTAB elements is no longer 
associated with the event variable. When 
statement 11 is executed, the event 
variable is set active and incomplete. 
After the on-unit has been executed, the 
wait module sets the EVTAB element and 
event variable for E1 complete 'and 
inactive. It then tests any remaining 
EVTAB elements to determine whether they 
were set complete during an on-unit; in 
this case, it finds that the next EVTAB 
element (for E2) has been set complete and 
that there are no more events to process. 
Execution therefore continues until 
statement 4 is executed, at which time a 
new EVTAB element is created for E2 and 
chained to its event variable. 

Problem 2: A method must be provided to 
signal that an event waited on in an on- 
unit is already being waited on in the 
procedure that caused entry to the on-unit. 
Suppose that the RECORD condition is 
encountered in the operation associated 
with E2 (statement number 2) during 
processing of the WAIT at statement number 
3. The following then takes place: 

1. Control passes to procedure M. 

2. A further WAIT on E2 is encountered 
(statement number 9). Since E2 cannot 

now be completed, a mechanism must be 
available to raise the ERROR 
condition; otherwise, the program 
would never get out of the wait state. 

The problem is solved by setting a flag 
in the event variable whenever an on-unit 
is entered during WAIT statement 
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processing. If the wait module is 
subsequently reentered from an on-unit, to 
process a WAIT on the same event, it finds 
that this bit is set and raises the ERROR 
condition. 

Problem 3; If there is a GOTO out of an 
on-unit, this involves setting an event 
variable complete, and terminating the WAIT 
statement. Suppose the TRANSMIT condition 
is raised during the WAIT statement 
numbered 3, 4, or 9. The procedure L is 
entered and the following takes place: 

1. E3, which is a dummy event, is set 
complete. 

2. A GOTO is executed to the label 
BOOTLE. 

If no other action were taken, the event 
that caused entry to the on-unit (either E1 
or E2) would not be set complete; any 
subsequent WAIT on that event would thus 
cause the wait module to be invoked, with 
unpredictable results. The problem is 
solved by setting a flag bit in the current 
DSA whenever the wait module is called. 
(The method is similar to that used to 
cater for a GOTO out of a SORT exit, and 
uses the same flag bit.) If the GOTO 
module finds that the bit is set, it 
returns to the wait module; the wait module 
sets the event variable complete and 
inactive and then returns to the GOTO 
module to continue the GOTO out of the on- 
unit. Only the event that caused entry to 
the on-unit is set complete. Any other 
incomplete events specified in the WAIT 
statement are left incomplete. 

Pro ble m 4; If control reaches label BOOTLE 
without the TRANSMIT or RECORD condition 
haying been raised, the event E3 can never 
be completed. Some method must be 
available of making this fact known, 
otherwise the program would go into an 
indefinite wait on an event that could 
never be completed. This problem is solved 
by setting an event variable active only 
when it is associated with an operation. 
Thus, if a WAIT statement specifies an 
event that is inactive and incomplete, the 
wait module causes the program to be 
terminated. (If a WAIT statement specifies 
more than one event and one of the events 
is inactive and incomplete, the program is 
not terminated immediately because it is 
possible, although unlikely, that the 
incomplete event will be completed by the 



COMPLETION pseudovariable in an on-unit 
entered as a result of an I/O condition 
raised while processing one of the other 
events specified in the WAIT statement.) 



Control Blocks 



Four control blocks are involved in the 
implementation of the WAIT statement. 
These are shown in detail in appendix B. 

1. Event variable. Used to hold all 
information about the event at a PL/I 
level. Fields indicate whether it is 
active or inactive; complete or 
incomplete; whether it is already 
being waited on at a previous 
interrupt level; the type of operation 
with which it is associated. Each 
event variable contains the address of 
its associated ECB or CCB and, if it 
associated with an I/O event, the 
address of the FCB for the file. 

2. ECB (event control block) . Used to 
hold information about the event at 
the system level. For I/O events, ECBs 
are part of the DTF. For DISPLAY 
events, the equivalent control block 
is known as a CCB (channel control 
block) . 

3. EVTAB (event table). Created for each 
entry to the WAIT module; comprises an 
element for every incomplete event 
that is to be waited on. The EVTAB is 
held in a VDA acquired by the WAIT 
module. 

4. ECB list. This is a list of ECB 
addresses that is created in 
circumstances that are explained 
below. The ECB list is held in the 
VDA described above, and acts as an 
argument list for the WAITM macro 
instruction. 



Multiple-Wait Module (IBMDJWT) 



The actions of the multiple-wait module, 
IBMDJWT, are shown in the flowchart in 
figure 11.7, and are described in detail in 
the publication DOS PL/I Resident Li bra ry 
Program Logic. 
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Call display module to 
clear storage 



c 



Start 



J 



Branch to point in transmitter 
where WAITF is issued 



IBMBRIO& 
TRANSMITTER 



Issue WAITF macro instruction 




Call error handler which 
may in turn call on-units 



No 



Q 



Yes 




CHECK 
SUBROUTINE 



No 



IBMBRIO 



Issue WAITF macro and 
check for ON-conditions 



Return to caller 



J 




Decrement count of 
events to be completed 
by correct number. 
Set EVTABs as inactive 



No 



Decrement count by one 
for event completed in 
IBMBRIO 




Figure 11.7. (Part 
WAIT statement 



1 of 2) . Simplified flowchart of modules used in execution of 
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c 



Start 



D 



Remove any completed 
events from list 



WAIT MODULE 
IBMBJWT 




No 



No 



Build EVTAB and ECB 
list (from CCBs for 
DISPLAY event) in VDA 



Issue WAITM on 
ECB list 





Build EVTABs in VDA 




1 


r 










Call CHECK subroutine 
with one item in list 


o 


i 


r 




CHECK subroutine 


Handles one event and 
returns if all events not 
complete 









Call CHECK subroutine 
with first event returned 
from WAITM 



Build new ECB list 
for incomplete events 



CHECK subroutine 



Handles one event and 
returns if all required 
events not complete 



No 




Yes 



Figure 11.7. (Part 2 of 2). 
WAIT statement 



Simplified flowchart of modules used in execution of 
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As the flowchart shows, the WAIT module 
sometimes issues a WAITM macro instruction, 
and sometimes relies on the WAITF macro 
instructions in the PL/I transmitters. The 
reasons for this are as follows. 

The WAITF macro instruction in the 
transmitter can only be used for I/O 
events, and only one transmitter can be 
called at a time. If only a certain number 
of the events in an event list, need to be 
completed, it is uneconomic to pass these 
events one at a time to the transmitter, 
because the first event passed could be the 
last to finish. Consequently, whenever non- 
1/0 events are involved and_jwhenever only a 
specified number of events in an event list 
have to be completed, an ECB list is 
qenerated for all incomplete events and a 
WAITH macro instruction is issued. 

The WAITM macro instruction returns 
control as soon as any event in the list is 
complete, thus allowing an event list to be 
handled efficiently when only a number of 
events have to be completed. For I/O 
events, it is still necessary to issue the 



WAITF macro instruction in the transmitter, 
even though the events are known to be 
complete. This is because the WAITF macro 
instruction carries out various checking 
functions. 



Single-Wait Module (IBMGJWT) 



When the WAIT statement is handled by the 
resident library routine IBHGJWT, only one 
event can be waited on in any WAIT 
statement. The housekeeping problems are 
therefore considerably less complicated 
than those encountered when handling waits 
on multiple events. No EVTABs, or ECB 
lists are needed. When the module is 
entered, it either calls IBMDRIO for an I/O 
event, or issues a WAIT macro instruction 
using the CCB for a DISPLAY event, calling 
the DISPLAY module IBMDJDS to clear the 
working storage and check for any 
transmission error. 
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Chapter 12: Debugging Using Dumps 



The DOS PL/I Optimizing Compiler allows the 
programmer to obtain an execution time dump 
either by calling PLIDUMP or by specifying 
DUMP in the options statement. If he 
specifies DUMP in the options statement a 
dump will be given if the program is 
stopped because of the EBROR condition. In 
both these situations a formatted PL/I dump 
is given. A DOS system dump will not be 
produced except in exceptional conditions 
unless it is specified by the programmer 
using the Q option of PLIDUMP. 

Certain types of program error, result 
in overwriting of the control information 
used by the PL/I error-handling routines, 
thus causing a program check to occur. If 
this occurs whilst a previous program check 
is being handled, a system dump will be 
generated even if NODUMP has been specified 
in the JCL. A dump is produced because the 
program check exit is reset during the 
handling of program check interrupts. (See 
chapter 7, "Error Handling" for further 
details.) If DUMP has been specified in 
the JCL, it is, possible (though most 
unlikely) that a DOS system dump will be 
generated for other abnormal conditions, 
such as a rapid succession of program check 
interrupts. 

Furthermore, it is always possible for 
the programmer to ask an operator to take a 
stand-alone dump at any point in the 
program. The need to do this should, 
however, occur only infreguently. 



How, to UJ5 e_ t his Chapter 



This chapter contains information on how to 
obtain and interpret dumps, and on how to 
identify compiled code, data, and control 
blocks. Some knowledge of the compiler's 
housekeeping scheme, described in other 
chapters of this book, is assumed. Trying 
to use a dump without this knowledge can 
result in a great deal of wasted time. To 
acguire a quick overall picture, chapter 1 
and the introduction to chapters 6 and 7 
should be read. A summary of how to use 
this chapter when debugging is given in 
figure 12.1. 

This chapter is divided into three 
sections: 

Section 1 : How to obtain a PL/I dump 

Section 2: Recommended debugging 
procedures 



Section 3: 



Locating specific 
information 



Section 1 explains how to obtain a 
hexadecimal dump of a PL/I program. It 
also gives some suggestions on the use of 
various compiler and PL/I options that may 
prove useful when debugging. 

Section 2 offers two recommended courses 
for debugging a PL/I program by use of a 
dump. The first course deals with a PL/I 
dump that has been called from an EBEOR on- 
unit and is being used to debug the problem 
program. The second course deals with the 
situation in which a DOS system dump has 
been generated, probably because the 
housekeeping control blocks have somehow 
been overwritten. 

Section 3 describes how to find various 
data areas and other information. It is 
indexed and numbered for quick reference. 

Before taking a dump. Section 1 should 
be read, because the methods used are not 
those familiar to programmers using the DOS 
system. Sections 2 and 3 are for use when 
debugging. Programmers who know what they 
are looking for should refer directly to 
the contents table in section 3. This will 
direct them to numbered sections which give 
details of how to find particular items. 
Programmers wishing to follow some 
organized plan can follow the recommended 
procedures in section 2. Section 2 
crossrefers to the items in section 3, so 
that the details of the steps involved may 
be guickly found. 



Section 1: How to Obtain a PL/ 1 Dump 



In order to get a formatted PL/I dump, the 
programmer can either include a call to 
PLIDUMP in his program, or specify the 
option DUMP in his JCL. If he specifies 
DUMP in his JCL a dump will be given if the 
program terminates with the essay. 

The statement CALL PLIDUMP may appear 
wherever a CALL statement may legitimately 
be used. It has the following form: 

CALL PLIDUMP 

(character-string-expression 1, 
character-string-expression 2) ; 
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HOW TO USE THIS CHAPTER WHEN DEBUGGING 



( start ) 




No 



Read section 1 of this chapter to discover correct 
method. (Use of the DUMP option will not produce 
a dump) 



Yes 




No 



Do not attempt to debug without this knowledge. Read 
chapter 1 and introduction to chapters 6 and 7 of this 
book. 



Yes 




Yes 



Examine contents list at start of section 3 to find 
quickest method of finding item. 



IP No 




Yes 



Use contents list at start of section 3 to simplify finding 
various items. 



No 



Follow the most suitable check list in 
section 2 of this chapter. Refer to 
keyed items in section 3 for details. 



Figure 12.1. How to use this chapte r when de bugging 
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Character-string-expression 1 is a "dump 
options" character string consisting of one 
or more of the following dump option 
characters. The maximum length of this 
string is 256 characters. Defaults are 
underlined. 

T Trace. A calling trace thiough all 

active DSAs is generated. When an on- 
unit DSA is encountered, the values of 
the relevant condition built-in 
functions are given. The reason for 
the entry to the on-unit is also given 
if the ERROR or FINISH conditions are 
raised as standard system action for 
another condition. 



NT No trace, 
given. 



A calling trace is not 



F File information. A complete set of 
attributes for all open files is 
given, plus the contents of all 
accessible buffers. 

NF No file information reguired. 



Stop. The program will be terminated 
after the dump. 

Continue. Execution of the program 
will be continued after the dump. 



other options are negated. To obtain 
a DOS system dump using the Q option 
should be specified thus: 

CALL PLIDUMP(»Q NH ND NR NB NF NT'); 

There is no reguirement for a dump 
identifier because this will not be 
reproduces on the DOS system dump. 

NO. A DOS system dump is not reguired. 



D Debug. Additional information about 
files will be given. This includes 
the name of the transmitter and the 
open module, and information on 
whether ENDFILE or an error has 
occurred on the file. 

ND No debug. The additional files. 

60 The hexadecimal notation will be 

translated into the 60 character set. 

48 The hexadecimal notation will be 

translated into the 48 character set. 

The default options are TFCRDNHNB60. 
That is, trace information, file 
inforiation, debug file information, 
storage report, block information, no 
hexadecimal dump, continuation after the 
information has been put out, and 
translation into the 60 character set. 



H Hexadecimal. A hexadecimal dump of 

the partition will be given. If trace 
information is reguested, the TCA and 
DSA addresses will be given. If file 
information is reguested, the 
addresses of the FCBs will be given 
and the contents of all accessible 
buffers will be printed in hexadecimal 
notation as well as in character. 

NH No hexadecimal dump reguired. 



B Blocks. The contents of the TCA, TIA, 
DSAs, FCBs, and file buffers are 
printed in hexadecimal notation. 

NB No block information reguired. 



Options are read from left to right. 
Invalid options are ignored, and if 
contradictory options are coded, the 
rightmost options are taken. A further 
discussion of the output that results from 
each of these options is given later under 
the heading "Contents of a PL/I Dump". 

Character-string-expression 2 is a "dump 
identifier" character string of up to 90 
characters chosen by the PL/I programmer. 
It is printed at the head of the dump. If 
the character string is omitted, nothing is 
printed. 



RECOMMENDED CODING 



R Report. The lengths and addresses of 
the main areas of storage in use 
immediately before the call to PLIDDMP 
are given. 

NR No report information reguired. 



Quick dump. This gives a DOS system 
dump with none of the formatting and 
other information provided by PLIDUMP. 
The Q option only takes effect if all 



Since PL/I dumps are transmitted onto the 
standard file SYSLIST, it is important to 
insure that SYSLIST is assigned to a line 
printer device. PLIDUMP can be called from 
anywhere in a program, but the normal 
method used when debugging will be to call 
PLIDUMP from an on-unit. As continuation 
after the dump is one of the options 
available, PLIDUMP can be used as a snap 
dump to get a series of dumps of main 
storage throughout the running of the 
program. 



Chapter 12: Debugging Using Dumps 163 



© © 





//job dumper 
//options link, dump, map 

//exec pliopt 



* PROCESS (CODE, MAP, GOSTMT, FLOW (n,m)); 



(SIZE, SUBSCRIPTRANGE, STRINGRANGE): 

DUMPER: PROC; 

ON ERROR CALL PLIDUMP ('HB', 'ERROR ON-UNIT DUMP' 



END; 



©Ensures that a system dump will be given 
in some exceptional circumstances. Does not 
produce a PL/1 dump. 

® These options give compiled code listing and 
static storage map/essential for interpreting 
any dump. 

_ » Provides trace of last n branch-out/branch-iK, 
5 ) points in up to m blocks, if SNAP or PLIDUMP 
with trace is used. 



© 



_ x Produces linkage editor map giving actual address 
Z ) of each module after the link-edit step. 



© 



_ , Two arguments can be passed to PLIDUMP. 
* i They are the dump options character string and 

the dump identifier. The format of the call 

statement is: 



CALL PLIDUMP (character-string-expression 1, character-string-expression 2); 



® Permits trace of statement numbers in original 
source program, and simplifies program checking. 



. Prefix options. The use of these PL/I checkout 
O ) options is strongly urged. Since, however, they 
cause an increase both in the size of object code 
and in execution time, it may be necessary to 
restrict their use to suspected blocks or statements. 



Dump options character string 
(Default is TFC) 

I 

T Trace information required 

NT No trace information required 

F File information required 

N F No f i le information required 
S Stop after dump 
C Continue after dump 

H Hexadecimal information required 
NH No hexadecimal information required 
B Control block information required 
NB No control block information required 
Also R, NR, Q, NQ, D, ND, 60, and 48, see text. 



Dump identifier character string 



Printed at head of dump. May be up to 90 
characters long. 



Figure 12.2. Coding dump options 
16«* 



Abbreviation 


Condition Name 


i 


AREA 


| AREA 




CHCK 


| CHECK 




COND 


| CONDITION 




CONV 


CONVERSION 




ENDF 


ENDFILE 




ENDP 


ENDPAGE 




ERR 


ERROR 




FIN 


FINISH 




FOFL 


FIXEDOVERFLOW 




KEY 


KEY 




NAME 


NAME 




OFL 


OVERFLOW 




EEC 


RECORD 




SIZE 


SIZE 




STRG 


STRINGRANGE 




STRZ 


STRINGSIZE 




SUEG 


SUBSCRIPTRANGE 




TMIT 


TRANSMIT 




OFL 


UNDERFLOW 




UNDF 


DNDEFINEDFILE 




ZDIV 


ZERODIVIDE 





Figure 12.3. Abbreviations for 
condition names used in PLIDUMP trace 
information 



Ey includi 
(•HB^'dump i 
unit or by in 
card "Content 
possible to o 
control block 
should an err 
is being incl 
be taken that 
statements vh 
requesting a 



ng the statement CALL PLIDUMP 
dentifier 1 ) ; in an ERROR on- 
cluding DUMP in the options 
s of a PL/I Dump", it is 
btain a hexadecimal dump, with 
s identified and formatted, 
or occur. If an ERROR on-unit 
uded in a program, care should 
there are no further ON ERROR 
ich might override the on-unit 
dump. 



Suggested code for use when debugging 
with a dump is given in figure 12.2. 



CONTENTS OF A PL/I DUMP 



The appearance of a typical dump produced 
by the PLIDUMP modules with the options 
TFHB is shown in figure 12.4. The contents 
of particular sections are described in 
detail below. 



Headings 

The dump is headed by the line 

***PL/I DUMP*** 

This is followed by the user identifier, if 
any, given as the second character string 
in the argument list of PLIDUMP. 

Trace Information 



A request for trace information results in 
the following output: 

1. A trace of every procedure, begin 
block, and on-unit that is active at 
the time of the call to PLIDUMP. For 
procedures, the procedure name and 
statement number from which the 
procedure was called are given. If 
the * H* option is reguested, the 
offset of the statement is also given 
as well as the entry point address and 
DSA address. Also, if the entry point 
used is not the main entry point and 
the statement number option is in use, 
the main entry name is given. 

2. For on-units, the values of any 
relevant condition built-in functions 
are given. The type of on-unit is 
given and, where the cause of entry 
into the on-unit is not self- 
explanatory, the cause of entry is 
also given (e.g., if an ERROR on-unit 
was entered because of a conversion 
error, this fact is given in the trace 
information) . The on-unit type is 
specified, using a three or four 
letter abbreviation. A list of these 
abbreviations is given in figure 12.3. 

3. When a hexadecimal dump is requested, 
the entry point address of each active 
block is also given, together with the 
address of its associated DSA. 

4. When the compiler FLOW option is in 
effect, the flow statement table is 
also given. 

5. If a hexadecimal dump is requested. 
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USER IDENTIFIER s EXAMPLE OF PLIOUMP 



* * * Pt/I DUMP * * » 



* * * CALLING TRACE * * * 



(TCA ADDRESS 009E08 I 

PLIOUMP HAS CALLED FROM STATEMENT NUMBER 3 AT OFFSET 00009E FROM A ERR TYPE ON-UNIT WITH ENTRY ADDRESS 0078FC 
(AND DSA ADDRESS 0OA628 I 

ERROR DIAGNOSTICS 
PL/I CONDITION DETECTED: CONV 

ONCODE - 612 INTERRUPT CODE, SEE LANGUAGE REFERENCE MANUAL 

ONCHAR =1 CHARACTER CAUSING CONVERSION ERRDR 

ONSQURCE *IF THIS DOES NOT RAISE CONVERSION NOTHING HILL 

STRING CAUSING CONVERSION ERROR 



AOORESS OF ERROR HANDLER' S SAVE AREA 00A438 

REGISTERS ON ENTRY TO ERROR HANDLER 



0000A3B8 
OOOOOOOO 



8000 TA1 A 
0000928A 



END OF ERROR DIAGNOSTICS 

HHICH HAS CALLED FROM A LIBRARY MODULE WITH ENTRY AOORESS 009BEO (AND DSA ADDRESS 00A3E0 I 
WHICH HAS CALLEO FROM A LIBRARY MODULE WITH ENTRY ADDRESS 008960 (AND DSA ADDRESS 0OA0O8 I 
HHICH HAS CALLED FROM A LIBRARY MODULE WITH ENTRY ADDRESS 007B08 (ANO DSA ADDRESS 0OA368 » 

HHICH HAS CALLEO FROM STATEMENT NUMBER 5 AT OFFSET OOOOAC FROM A PROCEDURE EXAMPLE HITH ENTRY ADDRESS 0078*0 
(AND DSA AOORESS 00A250 I 



* * * END OF CALLING TRACE * * * 



TRACE OF PL/I CONTROL BLOCKS 



TASK COMMUNICATIONS AREA 



ADOR. 
009E08 
009E28 
009E48 
009E68 
009E88 
009EA8 
009EC8 
009EE8 
009F08 



OFFSET 

00000 

00020 

00040 

00060 

00080 

OOOAO 

OOOCO 

OOOEO 

00100 



OOOOOOOO 
OOOOOOOO 
0000AO20 
0000900A 
582E0004 
O7FF0000 
D203D04C 
00009102 
OOOOOOOO 



OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
S8EE0000 
OOOOOOOO 
00509120 
07FE0000 

oooooooo 



FF009E08 
00009F28 
00009996 
OOOOOOOO 
19DF478C 
OOOOOOOO 
0001078E 
OOOOOOOO 
OOOOOOOO 



FF035DF8 
OOOOOOOO 
OOOOOOOO 
00009988 
00B29500 
180F9834 
02010056 
OOOOOOOO 
OOOOOOOO 



TCA IMPLEMENTATION APPENDAGE 



AODR. OFFSET 
009F28 00000 
009F48 00020 
009F68 00040 
009F88 00060 



00036000 OOOOOOOO OOOOOOOO OOOOOOOO 

F04E051F OOOOOOOO OCOOOCOO OOOOOOOO 

OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 

OOOOOOOO OOOOOOOO OOOOOOOO 00009260 



OOOOOOOO 00009E18 OOOOOOOO OOOOAOOO ...)8. 

0000A038 OOOOOOOO OOOOOOOO OOOOOOOO -• 

OOOOOOOO 800000CO 80000000 00009000 

0000998A 0000999A 0000928A OOOOOOOO 

C001478C 00AC180E 18E1181F S8FC00E0 

00209160 0001078E 91400001 478C00CC 

00549180 D054071E 161F58FC OOF407FF K K.... 

OOOOOOOO 00008FC8 OOOOOOOO OOOOOOOO . 

OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 



0O00A08O 000091C4 OOOOOOOO 05F058F0 ..- 0.0 

OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 0* • 

OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO .....................•••...••••• 

OOOOOOOO OOOOOOOO 000004A8 0000A248 



DYNAMIC SAVE AREA (LIBRARY) 



CONTENTS OF REGISTER SAVE AREA 

REGS 0->7 FF00A750 00007A3C 
REGS 8->15 0OOOA6D8 0O00A6F8 



» * * PL/I OUMP * » * 



AODR. OFFSET 
00A700 00000 
O0A72O 00020 
00A740 00040 
00A760 00060 
00A780 00080 
0OA7A0 OOOAO 
00A7C0 OOOCO 
00A7E0 OOOEO 
00A800 00100 
00A820 00120 
00A840 00140 
00A860 00160 
00A880 00180 
00A8A0 001AO 
00A8CG 00 ICG 
00A8E0 001E0 
0OA9OO 00200 
00A92C 00220 
00A940 00240 
00A960 00260 
O0A98O 00280 
OOA9A0 002AO 
00A9C0 002C0 
00A9E0 002E0 
OOAAOO 00300 
O0AA20 00320 
00AA40 00340 
OOAA60 00360 
00AA80 00380 
OOAAAO 003AO 
OOAACO 003C0 
OOAAEO 003E0 
00A800 00400 
00AB20 00420 
0OAB40 00440 
00AB60 00460 
00A880 00480 
OOABAO 004A0 
OOABCO 004C0 
OOABEO 004E0 
OOACOO 00500 
OOAC20 00520 
00AC40 00540 
00AC60 00560 
O0AC8O 00580 
OOACAO 005AO 

LINE TH 
OOACEO 005E0 
OOADOO 00600 
00AD20 00620 
0OA040 00640 
00A060 00660 
00A080 00680 
OOAOAO 006 AO 



88004780 
4E008F2E 
00009F28 
C8E340C9 
41000138 
50D01004 
550OCO0C 
D06492D0 
58F0F052 
OA104110 
471030E2 
41103138 
31381255 
5000D04C 
01340214 
58560000 
00024850 
44503444 
1A0C5810 
18070A04 
C00C47D0 
004C4110 
33189120 
5500C00C 
5810C028 
00000001 
07FE4110 
00634301 
00015021 
07F658D0 
F02ED202 
02021005 
47F0F020 
18214850 
47F04030 
206 30277 
98E5D00C 
C9C2D4C4 
005AD200 
C4E4D4D7 
00008000 
OOOOOOOO 
OOOOOOOO 
3100AC3C 
3100AC3C 
OOOOOOOO 
E SAME AS 
OOOOOOOO 
47F0FOOO 
100895FF 
F05A94BF 
4780F0A8 
05004000 
00124334 



O000A628 

0000A1E8 

47103288 

C2D440C3 

5810004C 

18D19288 

47D03050 

005C5840 

051FD207 

33245010 

41100064 

50100134 

47803138 

18714110 

00953457 

91806006 

00601255 

45E03318 

004C1E01 

18F105EF 

320E58F0 

324CS010 

005C4780 

47D03270 

4100101C 

OA021BFF 

34820700 

002C5021 

00704201 

10489580 

10051051 

10410A11 

59D0103C 

20569188 

92F 12063 

20642063 

07FE358E 

D2C4C4C1 

D07D6000 

405C405C 

0C0O0O03 

00000800 

OOOOOOOO 

40000005 

40000005 

OOOOOOOO 

ABOVE 

OOOOOOOO 

4 7F OF 000 

101E4780 

102C4530 

95C24000 

30004780 

F2791930 



00045866 
00007A3C 
FF00A4C0 
06D9074B 
1E015500 
D0009200 
58FOC048 
C0289608 
00DC1000 
130 50 50 
5010D050 
9280D05E 
41000320 
340A1807 
45E032C4 
4710317A 
47D031AA 
41103224 
5500C00C 
5070004C 
C04805EF 
D1349210 
32824110 
58F0C048 
4U01C24 
9110 DO 5C 
501032DA 
002C4201 
0O7041F0 
D05E4770 
0A110203 
9540D05E 
4780F020 
20504780 
415000 3D 
12554720 
C9C2D4C4 
5B5BC2C3 
5C405C40 
405CE4E2 
0000 AC70 
002008F0 
13000000 
0800AC60 
0800 AC80 
OOOOOOOO 

47FF001C 
47F0F02E 
F03E4A60 
F12C5846 
4780F0A8 
F0A80630 
4780F0C0 



5E008F6C 
0000 A2F8 
FFOOBOBO 
40F1F9F7 
COOC4700 
D0019107 
05EF5000 
00015030 
4 100 00 DC 
D0605820 
41100050 
9120400C 
5810D04C 
0A0418F1 
91805000 
48560004 
49503442 
50100134 
47003108 
9140005C 
5000D04C 
D05E45EO 
32829220 
05EF5000 
0A104110 
471032 B6 
41103432 
002C4301 
339C50F0 
F04692DO 
000C1050 
4770F062 
952000 5E 
40309108 
968020 50 
40580214 
D207E3C1 
D3D6E2C5 
5C40C505 
C5D940C9 
0000 AC78 
24008113 
OOOOOOOO 
20000001 
20000001 
OOOOOOOO 

47FF001C 
47F0F186 
104A9103 
00000640 
95C34000 
4600F090 
4640F0B2 



FFO0A778 
FF00A750 
F5F7F3F6 
F1400000 
301A58F0 
D04F4780 
004C0703 
002050CO 
411030E2 
C04058F2 
07030054 
47803104 
1E015500 
05EF5070 
471031AA 
58660000 
47D0319A 
9240 DOSE 
58F0C048 
47803224 
18714110 
3318020C 
D05E5010 
DO 4C 1871 
34820700 
41F00008 
4500 32DE 
00785021 
00589208 
D05C9621 
D2331008 
9621D0SC 
4770F02E 
20504710 
06504110 
2 09640 B5 
C9C2D4C4 
5B5BC2D6 
C440D6C6 
C4C505E3 
0800ACF0 
80000000 
00000079 
100 B 114 
1E000S40 
OOOOOOOO 

0A320000 
C901D1C6 
102B4710 
9200F2A2 
4780F0A8 
9201F2A2 
4940F270 



FF00A750 
OOO0A6D8 
60D3D4F5 
000076F0 
C07405EF 
30544100 
005C005C 
00445000 
50100134 
00041 2FF 
D0549248 
58250000 
C00C47D0 
004C4110 
9140D05F 
47F03188 
48503442 
9180D05C 
05EF5000 
41000BB8 
341A1807 
D092344A 
01344100 
41103422 
501032A2 
58D0D004 
00000304 
00784201 
D05D186E 
005C9640 
001450D0 
9680D05F 
4110FU6 
4024947F 
40E058F1 
47F04024 
D2E3C3C1 
D7C5D5D9 
405C405C 
C9C6C9C5 
3300D204 
OOOOOOOO 
47000000 
20000078 
30000081 
OOOOOOOO 

47F0FOO0 
C3C2E9C4 
F1904740 
91F04000 
4800F2A0 
47F0F0D4 
47BOF0DO 



00007A3C 
0000A6F8 
40C306D7 
90EB000C 
58F0D048 
00045810 
92400064 
012C4510 
411000E4 
4780 30E2 
00554120 
0200D05C 
312258F0 
31AA9210 
471031AA 
D2010060 
0210D069 
478031EE 
D04C1871 
581000 4C 
0A0418F1 
020ED09F 
06405810 
18070A04 
4110342A 
58E0D00C 
0000 ACOO 
00784301 
181O58F0 
D05F59D0 
1O3CD207 
5900 103C 
0A0290E5 
20S092F0 
001045EF 
40502056 
C9C204C4 
5B5BC2C4 
405C40D7 
09407A02 
C4E3C640 
OOOOOOOO 
0700AC3A 
0500B113 
OOOOOOOO 
OOOOOOOO 

47F0F02A 
F3F99026 
F13A9140 
4710F0A8 
4130F279 
18304304 
920B6000 



5E007952 
OO00A250 
E809C9C7 
05301851 
90F01048 
D04C1E01 
02760065 
308805F0 
92 10005 E 
91802000 
D05405EF 
200047FO 
C04805EF 
D05E5010 
58650004 
50004165 
346C0650 
41000BB8 
41103412 
1E015500 
05EF5070 
34504SE0 
OQ4C1E01 
18F105EF 
450032A6 
980B0014 
0A024120 
00704122 
005805EF 
103C4770 
1040000C 
4770F02E 
D00C0540 
20630650 
000C9240 
94802050 
D2C6C1C1 
E4D4D740 
D361C940 
2B006006 
40000000 
OOOOFFOO 
40000006 
60000079 
OOOOOOOO 
OOOOOOOO 

47F0F02A 
F258S860 
102C4780 
95C 14000 
41330012 
00004140 
4530F12C 
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.V IBMDKPTAIBMDKTCAIBMDKFAA 

IBMDKODA$$BCLOSE$$B0PENR($BDUMP 
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..0..KMDTF ... 
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the address of the TCA is printed at 
the head of the trace. 

6. If either a hexadecimal dump or 

control block information has been 
requested, and any ERROR on-units are 
found, then the following information 
is also included: 



| provided. The name of the transmitter and 

| open module associated with the file are 

| provided, and other data regarding the 

| status of the file is given. This includes 

(whether an error has occurred on the file 

land whether ENDPAGE or ENDFILE have been 

^raised. 



a. The address of IBMDERR's DSA. 

b. The contents of the general and 
floating point registers at the 
time IBMDERB was called. 

c. If there was an interrupt, the 
address of the interrupt. 

d. A trace of library DSAs back to 
the last compiled code DSA. 



File Information 



A reguest for file information results in 
the following output: 

1. The default and declared attributes of 
all open files are given. 

2. Buffer contents of all buffers are 
given. If a hexadecimal dump has been 
requested, the contents of the buffers 
are given in both hexadecimal and 
character notation. If no hexadecimal 
dump is reguested, the contents are 
given in character notation only. 

If the ' B' option is included the the 
contents of the FCB, ENVB and DTF, and for 
VSAM files the IOCB and ACB are given. 

Due to the many possible variations in 
length of these blocks, the full control 
block may not always appear in this section 
of the PLIDDMP. 

The description of the MEDIUM option 
contains the following abbreviations: 

UNIT Unit record device (card reader, 
printer etc.) 

TAPE Tape unit 

DISK Disk storage unit 

INDE Device independent 



Debug Option 



If the debug option is specified, 
additional information about files is 



Hexade cimal Dump 



This is a dump of the partition associated 
with the program. The dump is set out in 
four columns. The first column contains 
the address in main storage. The second 
and third columns contain four fullwords 
each in hexadecimal notation. The fourth 
column is a reproduction of the second and 
third columns in character form. You can 
(specify whether you want the translation to 
(be into the 60 or 48 character set by using 
(either the ^O 1 or '48 1 option. 60 is the 
default. 

The PL/I hexadecimal dump is headed by 
the contents of the communications region 
and, if no trace information was requested, 
by the values of registers 12 8 13 and the 
floating point registers on entry to the 
dump. It should be noted that if the dump 
was called from an on-unit, these values 
are no t the values of the registers at the 
point of interrupt. The method of finding 
the register values at the point of 
interrupt is described in section 3, 
"Locating Specific Information." 



Block Option 



When the block option is used, the contents 
of the TCA, the TIA, and the DSAs in the 
LIFO stack (that is, all active DSAs) are 
printed in hexadecimal and character 
format. The absolute address is printed in 
the left hand column; the jofXset^^wl/thin 
the block are thea-printed. This is 
followed— by the contents of the block, 
first in hexadecimal and then in character 
notation. For DSAs, the type of DSA is 
shown; i.e., library DSA, procedure DSA, 
on-unit DSA, or dummy DSA. The contents of 
the FCBs, ENVBs, DTFs etc for any open 
files are printed in a similar format. 
I 



I Report Information 



(The report option gives a report of the use 
| of main storage immediately before the 
(PLIDDMP was taken. It gives addresses and 
(lengths of the major areas of storage and 
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shows how much storage in the partition is 
not in use. If the PL^I p rogram was call ed 
from a program in another language that 
specified the sto rage area to be used, 
figures for the total used and unused 
storage max be inacc urate. 

As described in chapter 1 and chapter 6, 
the partition used by a program compiled by 
the PL/I Optimizing Compiler is divided in 
a standard manner. A typical storage 
layout and related report are shown in 
figure 12.3. The partition is headed by 
the problem program which consists of 
compiler output link-edited with PL/I 
library routines. This is followed by an 
area of housekeeping control blocks known 
as the "program management area". The 
storage between the end of the program 
management area and the end of the 
partition is allocated dynamically, this 
area is known as the ISA (initial storage 
area) . During execution, two storage 
stacks are created, one starting at each 
end of the ISA. One stack is the LIFO 
stack containing all storage that is 
acguired and freed on a last-in/first-out 
(LIFO) basis. This stack contains 
housekeeping information for each PL/I 
block, storage for automatic variables, and 
workspace. In the PLIDUMP storage report 
this area is referred to as "primary LIFO 
storage", and shown on the line numbered 

04. The other stack starts at the end of 
the partition and contains all storage that 
is not acguired and freed on a last- 
in/first-out basis. This includes items 
such as controlled and based variables, 
transient library routines, I/O buffers, 
and control blocks associated with files. 
In the PLIDUMP storage report table this 
area is referred to as the "primary non- 
LIFO area" and shown on the line numbered 

05. Both stacks extend into an area of 
unallocated storage known as the major free 
area. Within the non-LIFO stack certain 
areas may be freed which cannot be 
incorporated into the major free area. 
These are listed in the PLIDUMP storage 
report table with the line number 06 and 
headed "free area". In certain situations 
these free areas can be used for further 
segments of LIFO storage. Such segments 
are listed in the PLIDUMP report table with 
the line number 07 and are headed "LIFO 
overflow segment". When LIFO overflow 
segments have been allocated, the figures 
for total used storage and total unused 
storage on lines numbered 09 and 10 in the 
storage report table will be inaccurate. 
The total used storage will be 
overestimated. The overestimate will be 
smaller than the largest LIFO overflow 
segment. 



Using the REPORT Op tion for Pr og ram 
Tuning 



As well as its use for debugging, the 
report option can be used for estimating 
the optimum storage size for a program. 
When this is done PLIDUMP should be called 
when the maximum amount of storage is in 
use. This will be at the point when the 
greatest number of blocks are active, the 
greatest number of files are open, and the 
largest allocations of based or controlled 
variables have been made. PLIDUMP can be 
called in a number of places to get an 
accurate picture. As well as using the 
report option, it may be useful to use the 
trace and file options. The file option 
will tell what files are open, and the 
trace option will show the point in the 
program where the report was taken. These 
options are defaults, and to get a dump of 
this type the following PL/I statement 
should be included: 

CALL PLIDUMP ('ND 1 , 'REPORT FOR TUNING 1 )*. 

"ND" overrides the debug option and reduces 
the output. "Report for tuning" is the 
dump identifier and is used to show the 
purpose of the dump. When the maximum 
amount of storage used in the program has 
been established, the figure should be 
rounded ip to the nearest K bytes and a 
safety margin added. A suggested minimum 
is 2K bytes if SYSPRINT is open and~4K 
bytes if it is not. (The extra 2K for 
SYSPRINT allows error messages to be 
produced.) 



Section 2: Recommended Debugging 
Procedures 



The main difficulty in reading a dump of a 
PL/I program is knowing where to start. 
The signposts known to assembler language 
programmers are of little help. There are, 
however, five main sources of information 
to be considered when using a dump to debug 
a PL/I program. They are: 

1. The statement number and the address 
where the error occurred (if the dump 
was taken after an error) 

2. The type of error (if the dump was 
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MAIN STORAGE LAYOUT 



PARTITION 
AREA 



r ADDR 
7800 



C6B8 
C968 

D938 

34FB8 

35800 
35808 

35A60 

35D00 

V 36000 



PROBLEM PROGRAM AREA 



PROGRAM MANAGEMENT AREA 



PRIMARY LIFO STORAGE 



MAJOR FREE AREA! 



NON-LIFO STORAGE AREA 



IFREE AREA IN NON-LIF0 STORAGE! 



NON-LIFO STORAGE AREA 



TRANSMITTER AREA 



TRANSMITTER AREA 



*\ 



> PRIMARY NON-LIFO AREA 



Unused storage is shaded thus 



ASSOCIATED STORAGE REPORT 



USER IDENTIFIER : REPORT 1 

01 .PARTITION AREA 
02. PROBLEM PROGRAM AREA 
3. PROGRAM MANAGEMENT AREA 
04.PKIMARY LIFO STORAGE 
5. PRIMARY NON LIFO AREA 
INCLUDING 

06. FREE AREA 

06T.FREE AREA TOTAL 

08. TRANSMITTER AREA 

08. TRANSMITTER AREA 

08T. TRANSMITTER AREA TOTAL 
09. TOTAL USED STORAGE 
10. TOTAL UNUSED STORAGE 



* * * PL/I DUMP * * * 

* * * STORAGE REPORT * * * 

FROM 007800 TO 036000 LENGTH HEX 
FROM 007 800 TO 00C6B8 LENGTH HEX 
FROM 00C6B8 TO 00C968 LENGTH HEX 



FROM 
FROM 



00C968 TO 
34FB8 TO 



FROM 035800 TO 



FROM 
FROM 



035A60 TO 
035DO0 TO 



00D938 LENGTH HEX 
036000 LENGTH HEX 

35808 LENGTH HEX 
LENGTH HEX 
3 5D00 LENGTH HEX 
036000 LENGTH HEX 
LENGTH HEX 
LENGTH HEX 
LENGTH HEX 



02F800 


DEC 


190464 


004EE8 


DEC 


20152 


0002B0 


DEC 


688 


000FD0 


DEC 


4048 


001048 


DEC 


4168 


000008 


DEC 


8 


000008 


DEC 


8 


0002A0 


DEC 


672 


000300 


DEC 


768 


000 5A0 


DEC 


1440 


007178 


DEC 


29048 


027688 


DFC 


161416 



* * * END OF REPORT * * * 
I Figure 12.5. A typical arrangement of main storage and an associated storage report. 
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taken after an error) 

3. The values in the general registers 
when the dump was taken or when the 
error occurred 

**. The chain of DSAs 

5. The TCA 

The first two of these items hold 
eguivalent information to that held in the 
PSW in a DOS system dump. The last three 
items enable the housekeeping to be checked 
and the location of the control blocks and 
the program variables to be discovered* 
The methods of locating other information, 
given in section 3, refer to the key areas 
shown above. 

When debugging, it is essential to have 
a listing of the object program and a 
linkage editor map. The object program 
listing allows the programmer to study the 
instructions that are being carried out and 
to find various control blocks in static 
storage. The linkage editor map allows the 
programmer to identify particular parts of 
the executable program phase and, for 
instance, to identify the routine 
associated with each DSA. It is also very 
desirable to have a variables offset map 
generated when the compiler MAP option is 
used. 



THE CONTENTS OF A DUMP 



The PLIDUMP and the DOS system dump both 
consist of a dump of the partition that is 
associated with the program. The principal 
contents of the partition are shown in 
appendix A. More detailed descriptions of 
the contents of main storage can be 
obtained from chapters 1 and 2. The 
partition contents will also appear in a 
stand-alone dump. The partition contains 
all information that is connected with the 
program. This will comprise the compiled 
code, any link-edited PL/I library modules, 
any transient PL/I library modules that are 
currently loaded, housekeeping control 
blocks, and all program variables. 



DEBUGGING PKOCEDUEES 



2. 



When PLIDUMP has been called from an 
EEEOR or other on-unit v 

When a DOS system dump has been 
generated 



Other possible situations are when a 
dump is taken at a specified point in the 
program, or when a stand-alone dump is 
taken. No attempt is made to suggest a 
course of action in these circumstances, 
because the reason for the dump being taken 
is not predictable. However, in such 
cases, the main storage situation can be 
investigated by following the methods 
itemized in section 3 of this chapter. 

Throughout each of the two recommended 
procedures given in the following 
paragraphs, there are cross-references to 
the methods given in section 3. The cross- 
references consist of the keys by which the 
methods are identified; for example, H6, 
D5. 



PL/I Dump Called from On-Unit 



If a PL/I dump is called from an EHBOR on- 
unit it can be assumed that the 
housekeeping system of the program is 
working. If it were not working, the dump 
would probably not have been generated. 

A large amount of diagnostic information 
will be available at the head of the dump. 
An error message will have been generated, 
and this will provide a useful starting 
point. The first step should be to examine 
the error type and the point at which it 
occurred. ONCODE and other condition 
built-in function values should be 
examined, as should the trace information. 
A suggested procedure is the following: 

1. Examine the error by means of the 
ONCODE and any other relevant built-in 
function values. These values are 
held in the trace information. (The 
meanings of oncodes are given in the 
language reference manual for this 
compiler.) 

2. Find the location of error (P1) and in 
which block the error occurred (H12). 
If error occurred in library module, 
see H14. 



The best approach to a dump depends on the 
problem to be solved and must therefore be 
left largely in the hands of the 
programmer. However, two suggested courses 
of action are given in this section. 

These courses cover two situations: 



3. Examine the trace to see if it appears 
as expected. 

4. Examine the information in the file 
buffers, and check that file 
attributes are as expected. This 
information will be printed in the 
dump heading. 
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5. Check the values of any variables 
involved in the interrupt (V1-V6). 

6. Check values of registers to see if 
dedicated registers are pointing to 
correct areas (H8 & H9) . Distinguish 
between compiled code and library 
register usage. 

7. Check housekeeping (H1-H16) starting 
with area most directly concerned with 
type of statement in which the error 
occurred. 

8. Check values of all variables in the 
program (V1-V6) . 

9. Check logic of code being executed 
from object listing. 



DOS S ystem Dump 



A DOS system dump consists of four columns 
of hexadecimal figures. The first column 
is the address in main storage; the second 
and third columns are the contents of main 
storage printed in hexadecimal notation; 
the fourth is the contents of main storage 
in character form, with a period for 
unprintable characters. Each column 
contains four fullwords. The dump is 
headed by the register values at the point 
when the dump was taken, and this is 
followed by the address of the 
communications region. 

A DOS system dump is generated when 
there is a failure of the error-handling 
modules, or of the module that prints the 
| PL/I hexadecimal dump, or when it is 
I reguested by the Q option of PLIDUMP or 
I when there is not enough main storage to 
(continue. It should be noted 
that the failure of these modules is more 
likely to be caused by the overwriting of 
essential information than by an error in 
the modules themselves. 

A DOS system dump will not normally be 
produced for program checks, because a 
program check exit is set by the PL/I 
housekeeping routines, so that the system 
returns all program checks to the error 
handler. In the error handler itself, the 
program check exit is reset so that a 
program check interrupt will result in a 
dump. 

Thus, a DOS system dump will be produced 
if the program check exit, which is 
normally set by the program initialization 
routines to prevent a dump, has been reset 
during the program, or, possibly, has not 
been set at all. The second alternative is 
extremely unlikely. A third possibility is 



that the program check exit itself is not 
working, and the STXIT macro in the 
initialization routines did not 
successfully set the program check exit. 
The most probable of these suggested causes 
is that the program check exit has been 
reset by the program. The program check 
exit is always reset for the duration of 
error handling or PLIDUMP, to prevent 
looping should an interrupt occur. (See 
chapter 7, "Error Handling.") If an 
interrupt occurs during error handling, a 
dump is therefore produced. An interrupt in 
the error-handling routines indicates 
either that the error-handling routines are 
at fault, or, more probably, that some of 
the control information of the error- 
handling routines has been overwritten 
during the execution of the program. The 
most practical solution may be to re-run 
the program with SUBSCRIPTRANGE, 
STRINGSIZE, and STRINGBANGE enabled. 



However, having obtained a DOS system 
dump, the following debugging procedure may 
be adopted. 

1. Determine whether dump was caused by 
program check. This can normally be 
discovered from the message printed on 
the page before the dump. If no 
message is printed, inspect the 
program interrupt key (PIK) in the 
communications region (D6) . 

2. Determine in which routines the error 
occurred. (D1 and 2 for address of 
interrupt, H2 for associating address 
with code.) Verify that this module is 
one called from error handler. (H3 
and H10 for identifying module; figure 
12.6 for modules called from error 
handler.) 

3. Investigate the error that caused 
entry into the error handler. This 
can be done by examining the contents 
of IBMDEER' s DSA (H7) and the 
associated ONCA (H6) . See whether 
incorrect information passed to the 
error handler could be causing a 
failure. If the instruction is within 
the program control section shown on 
the linkage editor map the address can 
be associated with a statement (see 
H.2). 

4. Locate instruction causing interrupt. 
This is done by looking for the PSW in 
the partition save area (DO) . 

5. Inspect this instruction to see if it 
appears to have been overwritten, 
bearing in mind the cause of the 
interrupt, e.g., 

a. is it a valid instruction? 
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RESIDENT 

LIBRARY 

MODULES 



TRANSIENT 

LIBRARY 

MODULES 





IBMDERR 

Error 

handler 
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IBMBEOC 

On-code 

calculator 




IBMDESM 
Error message 
module phase 1 


-— 


IBMBETx 
Message 
text module 
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IBMDEDW 

Console 

transmitter 




IBMDESN 
Error message 
module phase II 




IBMDSxx 

SYSPRINT 

transmitter 





























Figure 12.6. Error message group of modules 



b. is it a branch to a protected 
address? 

6. Inspect the TCA (D5) to ensure that all 
error-handling addresses are correct. 

7. Investigate the housekeeping fields, 
starting with the DSA chain (H1-H3) , 
then the chain of ONCAs (H5,H6). 

8. If none of the above actions produces 
any results, an error in the error- 
handling modules must be presumed. 
This cannot be investigated without a 
listing of the modules. Meanwhile the 
cause of the original entry to. the 
error handler has been discovered and 
can possibly be avoided by altering 
the source program so that the error 
does not occur. The trouble should 
nonetheless be reported, because a bug 
in the PL/I error-handling routines 
has apparently been discovered. It 
must be emphasized that the cause of 



entry into the PL/I error handler was 
not the cause of the system dump. 



9. If the interrupt is not in the error 
handler or PLIDUMP, or one of the 
routines they call, the highest 
probability is still that the program 
check exit was altered in the error 
handler and that an invalid branch has 
been made from one of the addresses in 
the TCA. A careful check should 
therefore be made in the TCA. (See 
appendix B for map of TCA.) If this 
fails to produce results, return to 
stage 2 of the above procedure. 

It may be possible to use the program by 
avoiding the cause of entry into the error 
handler discovered in 3 above. However, as 
the error is probably due to some kind of 
overwriting, simply bypassing the sta+~ ^nt 
identified in 3 may not have the de a 
results. 
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Section 3: Locating Specific 
Information 

This section tells the reader how to 
discover information from the dump. It has 
been produced in a modular form for easy 
reference. The reader should look through 
the following contents list to discover the 
items in which he is interested. Suggested 
methods of debugging a PL/I program from a 
dump are given in section 2 of this 
chapter. Unless the programmer is 
experienced in using dumps, or is looking 
for some particular item, the procedures in 
section 2 should be followed, rather than 
attempting to find various items through 
the information in this section. 



CONTENTS 



Key Areas.of u a„PL/I Dump 

P1 Statement number and address where 
error occurred (dump called from 
on-unit only) 

P2 Type of error (dump called from 
on-unit only) 

P3 Register contents at time of error or 
dump invocation 

P4 The DSA chain 

P5 The TCA 



Key Areas of a DOS System Dump 

DO Partition save area 

D1 Address of interrupt 

D2 Type of interrupt 

D3 Register contents at the point of 
interrupt 

D4 The DSA chain 

D5 The TCA 

D6 Finding program interrupt key (PIK) 

D7 Finding the communications region 

Stan d-Alone Dumps 

S1 Finding key areas in stand-alone 



dumps 



Housekeeping Informatio n in a ll Dump s 

H1 Following the DSA backchain 

H2 Associating instruction with correct 
module 

H3 Following calling trace 

H4 Associating DSA with block 

H5 Finding relevant ONCA 

H6 Following the chain of ONCAs 

H7 Finding information from IBMDERR^ 
DSA 

H8 Finding and interpreting register 
save areas 

H9 Register usage 

H10 Following free-area chain 

H11 Action if interrupt occurred at 

address not in linkage editor map 

H12 Block structure of program 
(static-backchain) 

H13 Forward chain in DSA's 

H14 Action if error is in a library 
module 

H15 Discovering contents of parameter 
lists 

H16 Finding main procedure DSA 



Finding Variables 

V1 Automatic variables 

V2 Static variables 

V3 Controlled variables 

V4 Based variables 

V5 Area variables 

V6 Variables in areas 
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Control Blocks and Fields 



C1 Quick guide to identifying control 
fields 



KEY AREAS OF A PL/I DUMP 



PI: Statement , Number and Address where 
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Alternatively the statement number table 
can be used (see H2) . 



P2J. Il£e_of_Error (Dump.Called. f rem 

On-Unit_cnly]_ 



The type of error is identified in the 
trace information, in terms of the type of 
on-unit entered and the reason for entry. 
The on-code is also given, thus providing 
further indication of tne cause of the 
condition. If the dump was called from an 
ERROR on-unit, an error message should have 
been generated before the dump. This again 
will give the cause cf the error. 

If no trace information has been 
generated, the type of error can be 
discovered from the error code appearing in 
the ONCA associated with the interrupt. 
The method for finding the ONCA is 
described in H5. 



P3j. legist er_Contents_at_Time_Of_ Err or 

or_Dump_Invocation 



If trace information has been generated, 
the contents cf the registers must be found 
from the save area in the DSA. The 



addresses of all DSAs appear in the trace 
information. The register contents 
required will depend on the situation. If 
PLIDUMP was called from an on-unit, the 
register contents at the time the condition 
was raised will be most useful, unless the 
condition was raised in a library module. 
If the condition was raised in a library 
module, the contents of the registers at 
the point where the library call was made 
will probably prove more useful. 

The method of finding the register 
contents is as follows: 
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2. If the interrupt was a program check 
interrupt (see figure 12.7), the 
contents of registers 14 and 15 will 
also be stored in the DSA, register 14 
at of f set ,«5C (92) and register 15 at 
offset '60' (96) from the head of the 
DSA. 

3. Registers through 11 will be stored 
in the save area of the previous DSA, 
starting at offset • 14' (20) . 

4. If the interrupt was a software 
interrupt, the registers will be 
stored at offset 'C (12) of the DSA 
before IBMDERF's DSA in the order 14 
through 11. See figure 12.7. 

Discovering. if iuterrupt_was_2rogram__check 
±Sf§££MBi* If trace information is 
available, a check can be made on whether 
IBMBEEPA or IBHBERRB was called. IBMBERRA 
is entered after program check interupts, 
IBMBERRB after software interrupts. If no 
trace information is available, the 
simplest method of discovering if the 
interrupt was a program check interrupt is 
to inspect bit 7 in byte X'56' (86) in 
IBMDERR' s DSA. This is set to zero for 
program check interrupts, and to 1 for 
other interrupts. 
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Software detected interrupt 



Program check interrupt 



DSA of block in which 
interrupt occurred 



DSA of block in which 
interrupt occurred 



1 ► 



4 

8 
44 


4 




Backchain 


Registers 14 through 1 1 at time of interrupt 


Other DSA information 


DSA for IBMDERR 




Backchain, register save area, address 
of LWS, NAB, etc. 








50 


Qualifier for I/O, CHECK condition 


54 


1 st 2 bytes of error 
code passed to 
IBMDERR 








5C 


Not used 


84 





. ► 



4 

8 

C 

14 

44 


4 




Backchain 




Interrupt address from word 2 of PSW 




Registers through 1 1 at time of interrupt 


Other DSA information 


DSA for IBMDERR 




Address of interrupt DSA 








8 


Register save area, address of LWS, NAB, etc. 


54 


Error code created 
by IBMDERR 




58 




Interrupt code 


5C 


Register 14 at time of interrupt 


60 


Register 15 at time of interrupt 






68 


Floating point registers 0, 2, 4, 6 



Floating point registers are saved only if interrupt 
relates directly to a PL/I condition, and return may 
be made to the point of interrupt 

Figure 12.7. Information stored by IBMDERR after a program check and a software 
interrupt 
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BYTE 1 



PL/I CONDITION IF ANY 



BASE NO. 



X'OS' 
X'03' 
X'OU' 

x'os* 

X'06' 
X'07' 
X'08' 
X'09' 
X'OA' 
X'OB' 
X'OC 
X'OD 1 
X'OE' 
X'OF' 
X'10' 

x'ir 

X'12' 
X'13' 
X'14' 
X'15' 
XM6' 
X'CD' 
X'CF' 
X'D3' 
X'D5' 
X'D7' 
X'D9' 
X'DF' 
X'ET 
X'E3' 
X'E5' 
X'E7' 
X'E9' 
X'EB' 
X'ED' 
X'EF' 
X'FT 
X'F3' 
X*F5' 
X'F?' 
X'F9' 
X'FB' 
X'FD' 
X'FF' 



ZERODIVIDE 

FIXE DOVE RFLOW 

SIZE 

CONVERSION 

OVERFLOW 

UNDERFLOW 

STRINGSIZE 

STRINGRANGE 

SUBSCRIPTRANGE 

AREA 

ERROR 

FINISH 

CHECK 

CONDITION 

KEY 

RECORD 

UNDEFINEDFILE 

ENDFILE 

TRANSMIT 

NAME 

ENDPAGE 



no 



320 

310 

340 

600 

300 

330 

150 

350 

520 

360 

009 

004 

510 

500 

050 

020 

080 

070 

040 

010 

090 
9250 
1000 
9200 
3500 
4050 
5050 
5000 
9050 
1000 
4000 
on-code* 
4050 
0003 
1000 
1550 
1500 
2000 
3768 
3000 
3800 
3900 
9000 
8090 



* Permanent WAIT. Generates message and terminates. 



Figure 12.8. Error code field lookup table 
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bits 4 and 5 of a DSA, as follows: 
Bit_4 Bit_5 DSA 
Procedure block DSA 

1 Begin block DSA 

1 Library DSA 

1 1 On-unit DSA 

The value of register 12 can only be 
discovered in a DSA prior to a compiled 
code DSA, as it is not stored by the 
library when entering a routine. This means 
that the dummy DSA always contains the 
value of register 12. Register 12 should 
point to the TCA, whose address is also 
given at the head of trace information. 

No trace information^, genera ted: If no 
trace information has been generated, the 
register values on taking the dump will be 
printed at its head. The address of the 
DSA for PLIDUMP will be in register 13. 
The chainback can then be followed to find 
the DSA for IBHDEEE. The DSA for IBMDERR 
can be recognized if an on-unit is 
involved, because it will be the DSA before 
the on-unit DSA. IBMDERR's DSA will always 
be headed by a flag of hexadecimal '88' 
meaning that it is a library DSA in LIFO 
storage. To identify IBMDIRR's DSA for 
certain, register 15 of the previous 
block's DSA must be inspected to see if it 
points to the module IBMDERR. The position 
of IBMDERR is shown in the linkage editor 
map. 



P4: The DSA Chain 



in the dump-options character string, the 
complete TCA (including the appendage) is 
printed separately from the body of the 
dump. 



KEY AREAS OF A DOS SYSTEM DUMP 



The method of finding the key areas of a 
DOS system dump depends on finding the 
partition save area. The partition save 
area contains the eld PSW and the register 
values at the point of interrupt; from 
these the key items can be identified. The 
format of the partition save area is shown 
in figure 12.9. 



DO: Partition Save Area 



The partition save area immediately 
precedes compiled code and is found in the 
following manner. 

1. Use the linkage editor map to find the 
absolute address of the start of the 
program control section. 

2. Look immediately before the control 
section in the body of the dump. This 
will be the start of the partition 
save area. The partition save area is 

.120 bytes long and usually starts with 
the characters 'NO NAME'. Normally it 
starts at the head of background 
storage, which is headed by the 
letters BG . 



The addresses of the DSAs are given in a 
PL/I dump if trace information and a 
hexadecimal dump are requested. If trace 
information is not requested, the address 
of the DSA for the dump routine can. be 
obtained from register 13 at the head of 
the dump. The chainback field is held in 
the second word of the DSA. When the dummy 
DSA is reached, this chainback field will 
be set to zero. The DSA chain passes 
through DSAs in LIFO storage and DSAs in 
LWS. 

See H1 and figure 12.10 for details of 
how to fellow the DSA chain. 



P5: 



The TCA 



The address of the TCA is given in a PL/I 
dump. If 'B* (block option) is specified 



The contents of the registers and the 
old PSW are located in the partition save 
area at the offsets shown in figure 12.9. 



DJj Address_of .Interrupt 



The address of the interrupt can be found 
from the second word of the PSW, which 
gives the address of the instruction 
following the point of interrupt. To find 
the associated statement number see H2. 

Finding the statement number is not 
likely to prove useful because of the 
circumstances in which a DOS system dump is 
generated. The address found will usually 
be the address at which the error handler 
was entered before the program check exit 
was altered. The reason for entry into the 
error handler is net the cause of the dump. 
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Partition 


save area 


Normally 'NO 


NAME' 


P.S.W. 
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register 
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Floating point 


register 
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Figure 12.9. Partition sava area 
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To previous DSA 



Flags 



Reserved 



Backchain 



Not used 



Register save area (60 bytes) 



48 



4C 



50 



R13 



Address of library workspace 



Segment No. 



Segment No. 



NAB 



End of prologue NAB 



Space for automatic variables and temporaries. 
Length depends on number and type of 
variables declared in the associated block. 



Flags 



Reserved 



Backchain 



Current 
DSA 



NAB points to the 
next DSA only if it 
is in LIFO storage 
and has the same 
segment number 



Figure 12.10. DSA chaining 



D2i Tyj_e_of_ Interrupt 



The type cf interrupt can be found from the 
first wcrd of the FSW (see Princi£les_of 
Operation for details). 



D3i Beqister Conten ts ._atthe_Pgint._of 

Interrupt 



These are printed at the head of the dump, 
or can be found in the partition save area, 
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D4: 



The DSA Chain 



Register 13 should point at the most recent 
DSA. The back chain can be followed from 
offset '4' of each DSA. See figure 12.10. 



D5: The TCA 



register 12 should point at the TCA. 



D6i Finding Prggram_Interrupt K ey 
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The program interrupt key is held at offset 
hexadecimal *2E' (46) from the start of the 
communications region. It stores 
information on where the interrupt 
occurred; from this information it is 
possible to decide which PSW to inspect for 
the address of the interrupt. 



2§sk_in_ which 

interrupt 

occurred 

Background 

Foreground 2 

Foreground 1 

I/O 

Supervisor 



PIK_valu.e. Relevant_PSW 

X' 10' Old program PSW 

X'20' Old program PSW 

X' 30' Old program PSW 

X'50« Old I/O PSW 

X'60' Old supervisor PSW 



D7^ Finding the Communications Region 



The address of the communications region is 
printed at the head of a DOS system dump. 



STAND-ALONE DUMPS 



S1.i Finding Key. Areas_in_.Stand- Alone 

Dum£s 



From the linkage editor map, the address of 
the end of the executable. program phase can 
be identified. If the program is a 
straightforward PL/I program, the TCA will 
start at the first doubleword boundary 
following the end of the executable program 



HOUSEKEEPING INFORMATION IN ALL DUMPS 



Hli Folio wina_the_DSA_Backcha in 



Eacn DSA holds a backchain address in the 
second word. This word holds the address 
of the previous DSA. The end of the chain 
is marked by the dummy DSA whose first word 
contains the flag hexadecimal '82'. The 
backchain in the dummy DSA points to the 
external save area or is zero if the 
program was called from the system. (See 
P4 or D4 for finding the DSA chain) . 



H2j. Assoc iatin2_Instruction_with 

Correct, Statement _ and. Program, Block 

Statement Number., and „ Pro grain_„ i B lock 
The statement number and entry point 
associated with the interrupt will normally 
be given in a PLIDUMP. However, if they 
have to be found by the programmer, he 
should follow the method used by the error 
message modules. 
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The statement number is found by use of 
the DSA chain as described below: 

1. Find the chain of DSAs. The most 
recent DSA should be addressed by 
register 13. 

2. If the DSA found is not a compiled 
code DSA, (flag bits 4 and 5 set to 
•OO'B, »01'B or M1'B) the interrupt 
was not in compiled code. If the 
interrupt was in compiled code, the 
interrupt address can be directly 
associated with a statement number. 

If the interrupt was not in compiled 
code, the address at which compiled 
code was left must be discovered and 
this address associated with a 
statement number. To find the address 
at which compiled code was left: 

a. Chain back along the DSA chain 
until a compiled code DSA is 
reached (flag bits 4 and 5 set to 
'00» , »01' , or • 11'B) . 

b. The register 14 address saved in 
the DSA (offset 12 X'C) will be 
the point to which the library 
module or other module would have 
returned if the call had been 
successfully completed. 

The address thus found is the address to 
be associated with a statement number. 

3. Chain back one DSA to the DSA before 
the compiled code DSA that has been 
discovered in 1 or 2 above. The 
register 15 value in this DSA (offset 
16 X'10') is the entry point of the 
block. If this appears to give an 
invalid result, check to see whether 
the DSA is one of those used in 
interlanguage communication (flag bit 
7 set to '1'B and bit of flags 2 

(offset X'76«) set to M'B). If this 
is the case chain back one more DSA 
and try again. 

4. At offset 8 from the entry point of 
the block, the address of the 
statement number table will be held. 

5. Calculate the offset between the value 
in the first word of the statement 
number table and the address for which 
a statement number is required. If 
the address for which a statement 
number is required is less than the 
address in the first word of the 
statement number table, then either an 
invalid branch has been made, or a 
compiler generated subroutine is being 
executed. If it is possible that a 
compiler generated subroutine is being 
executed return to the compiled code 
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If the offset is more tha 
statement number will be 
second or subsequent sect 
table. Obtain the number 
translating the offset in 
ignoring the last 15 bits 
down this number of secti 
table. (For example, if 
was X'8FFF', translate to 
'1000 1111 1111 1111'B, i 
binary digits =1, thereto 
one section of the table, 
offset was X'18FFF' the b 
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Ignoring the 15 right han 
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The address of the second section of 
the table is held at offset X'8' in 
the table, the address of the third 
section is held at the head of the 
second section, the address of the 
fourth section at the head of the 
second section and so forth. 

When the correct section of the table 
has been identified, search for the 
first offset in the table that is 
greater than or equal to the offset 
that is being searched for. The 
statement number is in two-byte 
hexadecimal format and immediately 
precedes this offset. 



££2ced ur e_name : To find the entry point 
name, a chainback is made beyond the first 
££22£^iJ£s DSA found on the chain. Register 
15 in the save area before this procedure 
DSA will point to the entry point of the 
procedure. (Procedure DSA have flag bits 4 
and 5 set to '00'E. The register 15 value 
is held at offset 16 X'10'.) 

The entry is preceded by a one byte 
field .that holds the number of characters 
in the name. This one byte field is in 
turn precedad by the entry point name. 

Using th e table__of , of f sets : Statement 
numbers can also be found by comparing them 
with the offsets in the offset and 
statement number table generated by the 
compiler when the OFFSET option is 
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specified. 



H4 :. !ssociatin3_CSA_with_Block 



Offsets are held from each primary entry 
point or a procedure or on-unit. lo use the 
table of offsets find the entry point used 
by the program in the manner described 
above. Find the primary entry point for 
the procedure. (If the primary entry point 
was not used look at the object program 
listing to see the relationship between the 
entry point used and the primary entry 
point.) Note, the offsets given are from 
the point marked *R3EAL ENTRY in the object 
program listing. This point is one byte 
after the end of the primary entry point 
name. 



DSAs are associated with code by finding 
the register values in the register save 
area (H7) and using the fact that all 
branches are made via registers 14 and 15. 
Register 14 in any DSA points to the 
instruction after the point at which 
control left that block. Register 15 
points to the address at which the next 
block was entered. By comparing these 
addresses with the linkage editor map, the 
DSA can be associated with the correct 
block of code. 



If the interrupt occurred in an on-unit 
it may be necessary to discover the type of 
on-unit entered before it can be 
identified. This is done by inspecting the 
DSA before the DSA of the on-unit. This 
DSA will be for IBMDEER. At offset 84 
(X'54') in this DSA the first byte of the 
errcr code will be held. Compare this with 
the values in figure 12.8. This will give 
an associated PL/I condition. It will be 
the on-unit for this condition that has 
been entered. If there is more than one 
on-unit for the condition, the on-unit 
entered must be deduced by studying the 
dump, and source and object listings. If 
the register 15 value appears to be invalid 
this may be caused by rechaining in 
interlanguage processing (see chapter 13) . 
If this is possible, chain back one more 
DSA and try again. (To check if this has 
occurred see 3, above under "Statement 
Numbers") . 

Compare address of instruction with linkage 
editor map. This will give the name of the 
control section for compiled code cr a 
library module. If the address is not 
included in the linkage editor map, the 
address is probably in a transient routine, 
unless an invalid branch has been made. 
(See H11.) 



Hj>i Findina_Relevant_ONCA 



When an interrupt has occurred in the error 
handler and a system dump has been 
produced, it is possible to discover the 
information that the error handler would 
have used to generate appropriate error 
messages. The ONCA holds values for the 
condition built-in functions. The 
appropriate ONCA can be found in the 
following manner. 

1. Find the DSA before that of IBMDERR 
(follow back the DSA chain until 
register 15 in the save area points to 
IBMDEER). See H1, H3, H7. If this is 
a library DSA in library workspace 
(flag bit 4 set to ' 1'B and flag bits 
and 5 set to 'O'B) continue to step 
3. 

2. Find the LWS addressed from this DSA. 
This is held at offset X'48' (72). 

3. Find the offset from the LWS to the 
CNCA. This is held at offset 2 in the 
LWS. 

4. Add the offset to the address of the 
DSA in LWS. 



H3j. Follow in g_Calling_Tracg 



The calling trace can be followed because 
branches within the program are always made 
on registers 14 and 15*. Hence register 15 
in each DSA save area points to the address 
that was branched to from that block. 
Register 14 points to the address to which 
control passed when the block was 
completed. Ey comparing these values with 
the linkage editor map, it is possible to 
associate each DSA with the correct module 
of code. By following the backchain of 
DSAs (H1) it is possible to do this for 
every DSA and so discover the calling 
trace. The calling trace is printed in a 
PL/I dump. 



Illi^ r pr e t in£_t h e_Er r or_Co d e : The first two 
bytes of the error code are held at offset 
4 in the ONCA. These two bytes normally be 
translated into an encode which refers to 
the type of interrupt. The meaning of the 
oncode can be found in the language 
reference manual for this compiler. For 
PL/I conditions the first byte indicates 
the PL/I condition that has occurred. (See 
figure 12.8) . 

To translate the first two bytes of the 
error code into the oncode: 

1 . Find the base number associated with 
the value in the first byte (offset 
X«54V) . Figure 12.8 is actable of the 
byte values and their associated base 
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number. (Base values are in decimal) . 

2. Take the right hand five bits of the 
second byte (offset X*55') and 
translate these into decimal. 

3. Add this value to the base number 
found in 1 above. The result is the 
oncode for the interrupt that caused 
entry into the error handler. 

Example: 

Error code X'1266' 

Look up base value = 80 (equivalent PL/I 
condition UNDEFINEDFILE) 

Translate second byte to binary 
X'66«=0110 0110 binary 

5 right hand bits =0 0110=6 decimal 

0ncode=6 +base value=86 

E6z_ followinc[_the_Chain_of_ONCAs 



ONCAs are used to hold condition built-in 
function values. They are chained 
together, one being provided for every 
level of interrupt. The cnainback field is 
in the first word of the ONCA. The dummy 
ONCA is marked by a chainback field of 
zero. 

H 7 j Fin din g_ In form a t i o n_ f r o m_I B M D E E E J. s 

DSA 



The information held in IBMDEFR's DSA is 
that which is used by the error message 
modules for information about the error. 
It can be useful if the messages have not 
been generated, because the information can 
be deduced from the DSA. The contents of 
IBMDEER's DSA are shown in figures 12.7. 
See H4 for associating DSAs with correct 
code. 

Interrupt, Ad dress; The address of the 
interrupt that caused entry into the error 
handler is held at offset 12 (X'C) in the 
DSA preceding the error handler's DSA. To 
find the statement number of the interrupt 
see H2. 



H8x Finding, and ., Interpreting Register 

Save Areas 



Register save areas are held at offset 
X'C (12) in all DSAs, including DSAs in 
LWS. Offsets and registers are shown in 
figure 12.11. Each DSA holds the register 
values as they were on exit from its block. 
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H9^ Se£ister_Usage 



Register usage is fully discussed in 
chapter 2, "Compiler Output." A summary of 
register usage, showing which registers are 
always used for a particular purpose, is 
given in figure 12.12. 



DSA 



Flags 


Backchain 


Not used 


R14(*) 'Tj^ 


R15C) 


R0 


Always stored by 
R1 library 


R2 


R3 


R4 _jP 


R5 -*k 


R6 


R7 


R8 Stored by library 
if required 


R9 


R10 


R11 W 


R 1 2 Stored by compiled code only 



(*) Not stored if hardware interrupt occurs 



Figure 12.11. The register save area 
in the DSA 
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H10: Following F ree- Area Ch ain 



Hill Action if Interr upt Occured at 

Address n ot i n Linkage Edit o r Ha p 



The free-area chain connects the areas of 
non-LIFO dynamic storage that have been 
used and freed, but have not been absorbed 
into the major free area. See chapter 6, 
"Storage Management." The chain starts at 
offset 8 in the implementation-defined 
appendage, which is addressed from offset 
X'28'(40) in the TCA. The end of the chain 
is marked with a zero entry. The length of 
each item is held at offset 0. The address 
of the next free area at offset 4. If 
there are no further free areas the word at 
offset 4 is set to zero. 



Register 


Compiled code 
usage 


Library usage 


R0 


Work register 


Work register 


R1 


Work register 


Work register 


R2 


Program base 
(*»**) 


Work register 


R3 


Static base 


Program base 




(**) 


(**) 


R4 


Work register 
(Temporary base 
if DSA>3896 
bytes) 


Work register 


P5 


Work register 


Work register 
(if used) 


R6 


Work register 


Work register 
(if used) 


R7 


Work register 


Work register 
(if used) 


R8 


Work register 


Work register 
(if used) 


R9 


Work register 


Work register 
(if used) 


R10 


Work register 


Work register 
(if used) 


R11 


Work register 


Work register 
(if used) 


R12 


TCA pointer 


TCA pointer 




(**) 


(**) 


R13 


Current DSA 


Current DSA 




pointer (**) 


pointer (**) 


R14 


Branch 


Branch 




register 


register 


R15 


I Link register 


Link register 



(*) The contents of the program base 
register are saved during in-line 
record I/O and TRT instructions 

(**) Dedicated register, i.e., the 
contents remain unchanged 
throughout the execution of the 
associated compiled code or library 
routine 



Figure 12.12. Register usage 



If the interrupt occurred at an address 
that is not mentioned in the linkage editor 
map, there are two possible explanations: 

1. The interrupt occurred in a transient 
module. 

2. An invalid branch has been made. 



To test whether the error is in a 
transient module, the backchain should be 
followed to see whether register 14 in the 
previous DSA points to an area reasonably 
close to the point of interrupt. If so, an 
invalid branch can be discounted. Further 
chain-backs should be made along the DSA 
chain (H1) until a register save area is 
found that contains a register 14 which 
points to an area in the linkage editor 
map. This will be the routine that called 
the transient routine. It will usually be 
possible to deduce which transient routine 
is involved from the calling module and the 
context of the code. 



If the most recent DSA is that of 
IBMDRIO the transient routine will be one 
associated with record I/O. The 5th, 6th, 
and 7th letters of the name of the module 
will be held in bytes 8-10 of the module. 
The letters are most simply found by 
inspecting the character translation of the 
dump. The first of these letters will 
always be R. The module will also be on a 
transmitter chain that starts at a word 
addressed from offset X'18 , (24) in the TCA 
appendage, which is addressed from 
X'28« (40) in the TCA. 



HJ.2J. Block Structure of, Program 

(Static Backchain). 



The block structure of the program can be 
followed from the address held at offset 
X'58'(88) in each compiled code DSA. This 
address holds the address of the compiled 
code DSA of the statically encompassing 
block. The chain thus formed is known as 
the static backchain. 
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H13: Forward Chain in DSAs 



The forward c 
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hain in DSAs is not supported 
er. However, a forward chain 
IFO stack can normally be 
se of the NAB pointer. The 
s held at offset yi*HC'(16) 

of each DSA. The last 
e chain points to the major 
f the NAB pointer contains 
pt «FF' in its first byte, the 
be followed, because it is not 
a single LIFO segment. The 
red is held in the last three 

the first byte contains the 
r (see C1) . The forward chain 

those DSAs in the LIFO stack 
include any DSAs in LflS. 



The address of the dummy DSA is held at 
offset X'10« (16) in the TCA appendage, 
which is addressed from offset X'28'(40) in 
the TCA. The dummy DSA can be recognized 
by the presence of X'82' in the flag byte. 



FINDING VAPIABLES 



The value of the variables in the program 
at the point of interrupt can be discovered 
by using offset map and the compiled code 
listing as a guide to their addresses, and 
then finding these addresses in the dump. 
The method used depends on the type of 
variable. 



V1: Automatic Variables 
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the DSA of the block in 
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variables offset map 
the compiler MAP option is 
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cde. (For finding the DSA 

the block, see H<4) . 



V2: Static Variables 



H15i Dis co vering,. Contents of .Parameter 

Lists 
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ers are giv 
rary PLM. 



list of words 
except during 
siticn cf a 
ram, find the 

save area of the 
g block, 
e the parameter 
d with the static 

of the called 
(H3) . The 
en in the 



H.I61 Fi^dina_Main_Procedure_DSA 



The main procedure DSA can be found by 
following the backchain of DSAs to the 
dummy DSA. The address of the main 
procedure DSA will be given by the last 3 
bytes of NAB in the dummy DSA. This is 
held at offset X«4C (76) in the dummy DSA. 



lly addressed by 
This offset is 
set map generated 
on is used. If 
s not been used, 
by studying the 
The value of 
the save area of 
DSA associated 



Static variables are norma 
an offset from register 3. 
given in the variables off 
when the compiler MAP opti 
the compiler MAP option ha 
the offset can be deduced 
listing of compiled code, 
register 3 can be found in 
the DSA. (For finding the 
with the block, see H4) . 



V3_x Controlled, Variables. 



As described in chapter 2, internal 
controlled variables are addressed by an 
anchor word that is held in the static 
control section. This can be identified 
from compiled code, where it will normally 
be addressed by an offset from register 3. 
Typical code would be: 

From this it can be deduced that the 
address of K is held at offset X'88 1 from 
register 3. 

External controlled variables are 
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addressed from control sections that are 
shown in the linkage editor map. The 
variable starts at an offset of ' 8 1 from 
the address held in the control section. 
The first four bytes contain a pointer to 
previous allocations of the variable, or 
are zero if there are no previous 
allocations of the variable. 



CONTROL BLOCKS AND FIELDS 



For simplicity, the methods of finding 
various control blocks are placed in an 
alphabetic table. Details of the control 
blocks can be discovered from the relevant 
chapters (see index) or from appendix B. 

As well as control blocks, various other 
items are included in the list. Where 
necessary, cross-reference is made to other 
sections in this chapter. 



V4: Based Variables 



Eased variables are located by finding the 
value of the defining pointer. This value 
is found by using one of the methods 
described above to find static, automatic, 
or controlled variables. If the pointer is 
itself based, its defining pointer must be 
found and the chain followed until the 
correct value is found. 

Typical code would be the following: 

For X BASED (P) , With P AUTOMATIC 

58 60 D 088 L 6,P 

58 E0 6 000 L 14, X 

P is held at offset X'88' from register 
13, and this address points at X. 

Care must be taken when examining a based 
variable to ensure that the pointers are 
still valid. 



V5_2 Area Variables 

Area variables are located in cne of the 
ways described above, according to their 
storage class. 

Typical code would be: 

For area variable A declared AUTOMATIC 

41 60 D 088 LA 6, A 

The area would start at offset X'88' 
from register 13. 



CJi, Quick Guide_to_Ident if ying_Control 

Fields 



V6: Variables in Areas 



Variables in areas are found by locating 
the area and then using the offset to find 
the variable. 



Automatic variables 

Backchain 

DSA backchain 
ONCA backchain 

BOS 

Controlled variables 

DED 



Diagnostic statement 
table 



DFB 



DSA 



DTF 



ENVB 



EOS 



Event variable 



FCB 



see "Variables" 



offset X'4» in DSA 
offset X»0« in ONCA 

offset X»8' from TCA 

see "Variables" 

deduced from object 
program listing 

addressed from 
offset , 8' from 
entry point of main 
procedure 

addressed from 
offset X'40« (64) in 
TCA 

addressed by 
register 13 (see P3 
and D3) 

addressed from 
offset XM8» (24) in 
FCB 

addressed from 
offset XM4' (20) in 

FCB 

offset X»C» (12) in 
TCA 

deduced from object 
program listing and 
knowledge of 
parameter lists of 
I/O and wait modules 

identified in PL/I 
dumps. Open file 
statement listing. 
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Flow statement table 



addressed from 
offset X«4C« (76) in 
TCA 



Static storage 



addressed by 
register 3 in 
compiled code. See 
P3 and D3 



Filename 



addressed from 
offset X' 10 1 (16) in 

FCB 



SIOCB 



object program 
listing 



Free-area chain 



Locator/descriptor 



LIS 



Module name (when 
interrupt occurs in 
library module) 

NAB 



offset »8« in 
implementation- 
defined appendage, 
which is addressed 
from offset X'28* 
(40) in TCA 



deduced from object 
program listing 

addressed from 
offset X'48» (72) in 
every DSA 

comparing address of 
error with link-edit 
map 

offset X'4C« (76) in 
DSA 



Symbol table 
Symbol table vector 
Start of program 
Segment number 

TCA 



Variables 

automatic 



Static listing 

Static listing 

linkage editor map 

first two bytes of 
BOS, EOS, or NAB. 
•FF*=1, «FE'=2 etc.* 

addressed by 
register 12. See P3 
and D3 



offset (shown in 
variables offset 
map) from DSA of 
block in which they 
are declared. See 
V1 



ONCA 



CNCE - start of 

dynamic CNCB 
chain 

- first static 

CNCB 

On-cells 



OCB 



PSW 

Parameter lists 

Register values 

ECB 



Statement freguency 
count table 



the offset of the 
associated CNCA is 
held in a halfword 
at offset *2' in 
each section of LWS 

offset X'60« (96) in 
DSA 



offset X'5C« (92) in 
DSA 

addressed from 
offset X'70' (112) 
in DSA 

deduced from object 
program listing and 
parameter list of 
open module, IBMDOCL 

see D2 

object program 
listing and static 
storage map 

See P3 and D3 

object program 
listing and static 
storage map 



X »80« in the TCA 



based 



controlled 



static 



area 



Variables in areas 



address of the 
pointer must be 
deduced' from the 
object program 
listing. This gives 
the address of the 
variable. See V2 

address referenced 
in compiled code 
holds latest 
allocation of the 
variable. A 
chain-back through 
the previous 
allocation can be 
made using the 
header chain. See 
chapter 2, and V3 

deduced from offset 
from register 3 in 
variables offset 
map. See V4 

as for other 
variables depending 
on storage class. 
See V5 

find address of 
area. Find variable 
from offset within 
areas shown in 
compiled code. See 
V6 



Chapter 12: Debugging Using Dumps 187 



♦When the first two bytes of EOS and BOS 
are greater than NAB, it means that an 
extra segment of storage has been used, but 
not yet freed. See chapter 6, "Storage 
Management." 
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Chapter 13: Interlanguage Communications 



The DOS PL/I Optimizing Compiler allows 
subroutines compiled on certain IBM COBOL 
or FORTRAN compilers to be used in PL/I 
programs compiled on the optimizing 
compiler. Similarly, it compiles PL/I 
programs that can be run as subroutines of 
either COBOL or FORTRAN programs. 

Facilities are also provided to overcome 
the addressing problems that arise when 
passing arguments to assembler language 
routines. These facilities are described 
under the heading "Options Assembler" later 
in this chapter. 

A full description of how the 
interlanguage communication facilities can 
be used is given in the language reference 
manual and the programmer's guide for this 
compiler. A detailed description of the 
library routines involved is given in the 
resident library PLM. This chapter 
explains the basic design principles used. 
It will assist in understanding the 
situation in main storage during the 
execution of a program involving 
interlanguage calls. 



Background to Interlanguage 
Communication 



The major problems involved in allowing 
procedures written in PL/I to be used with 
programs written in COBOL or FORTRAN are: 

1. The existence of different data types 
in the different languages. 

2. The different methods of holding data 
aggregates in the different languages. 

3. PL/I's use of locators when passing 
areas, arrays, strings, and structures 
as arguments. 

H. The need for programs compiled on PL/I 
and FORTRAN compilers to have a 
specially initialized environment in 
which to operate. 

The first of these problems must be solved 
by the programmer himself, by ensuring that 
arguments passed between the routines are 
of suitable data types. (Information in 
the language reference manual for this 
compiler enables the programmer to do 
this.) 

I The other problems mentioned above are 



handled automatically by the interlanguage 
communication facilities of the compiler. 
These problems are summarized below. 



DIFFERENCES IN DATA AGGREGATES 



Structures in PL/I and COBOL, and arrays in 
PL/I and FORTRAN, are held in different 
manners. 

COBOL structures are mapped as follows. 
Working from the start, each item is 
aligned to its required boundary in the 
order in which it is declared, the 
structure starting on a doubleword 
boundary. 

PL/I structures are mapped by a method 
that minimizes the unused bytes in the 
structure. Basically, the method used is 
first to align items in pairs, moving the 
item with the lesser alignment requirement 
as close as possible to the item with the 
greater alignment requirement. The method 
is described in full in the language 
reference manual. 

Take, for example, a structure 
consisting of a single character and a 
fullword fixed binary item. The fullword 
binary item has a fullword alignment 
requirement; the character has a byte 
alignment requirement. In PL/I, the 
structure would be declared: 

DCL 1 A, 

2 B CHAR (1) , 

2 C FIXED BINARY (31,0) ; 

and would be held thus: 



I B | 
i 



In COBOL, the structure would be declared: 

01 A, 

02 B, PICTURE X, DISPLAY. 

02 C, PICTURE S9 (9) , COMPUTATIONAL. 

and would be held thus: 



I B | 3 unused bytes | 

l 
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Calling routine 



Call to routine in 
other language 



apparent path 
I 



Called routine 



Routine of other language 
carries out required 
task and returns 



real 
path 




\ 


Intervening code 


\ 


Save old environment, 
set up new environment. 
If necessary, provide dummy 
data aggregate arguments 


real 
path 





▼ 
I 
I 
I 
I 
I 

apparent path 



real 
path 




Restore former environment. 
Where necessary, assign 
values in dummy data 
aggregate arguments to 
real arguments 



Calling routine 



Continuation of procedure in 
original language 



real 
path 



Figure 13.1. Principles of interlanguage communication 
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In FORTRAN, multidimensional arrays are 
held in column-major order- In PL/I, they 
are held in row-major order. Thus the 
second element in a FORTRAN two-dimensional 
array has the subscript (2,1), whereas the 
second element in a PL/I two-dimensional 
array has the subscript (1,2). 

Structures are not available in FORTRAN. 
The equivalent of arrays in COBOL are held 
as in PL/I. 



USE OF LOCATORS 



When passing arguments, PL/I passes the 
address of locators for areas, arrays, 
strings, and structures rather than the 
address of the items themselves. This is 
because the routine that receives the 
arguments may require information about 
bounds or sizes of the data passed, and 
this is accessible through the locator. 
Other languages, however, expect the 
address of the data. The correct type of 
argument list must therefore be set up when 
an interlanguage call is made. 



DIFFERENCES OF ENVIRONMENT 



IBH FORTRAN compilers and the PL/I 
optimizing compiler rely upon 
initialization routines to set up an 
environment in which the compiled code 
routines can operate. In FORTRAN, the main 
task of the initialization routine is to 
issue a STXIT macro instruction to initiate 
the FORTRAN error-handling scheme. In 
PL/I, the initialization routines prepare 
for the PL/I error-handling scheme and also 
prepare the way for dynamic storage 
allocation. Register 12 is pointed at the 
TCA, which is used for addressing a number 
of housekeeping fields and library 
routines. Register 13 is pointed at a DSA 
which contains a standard save area, a NAB 
pointer pointing to the next available byte 
in the LIFO stack, and various other 
housekeeping fields. (See chapter 1 and 
chapter 5 for a discussion of the PL/I 
environment.) 

When PL/I is called from either a COBOL 
routine or a FORTRAN routine, the PL/I 
environment must be set up before the 
program can be run. Similarly, when PL/I 
calls another language, the environment 
suitable for the program that has been 
called must be set up. 



THE BASIC PRINCIPLES OF INTERLANGUAGE 
COMMUNICATION 



The method used to solve the problems 
outlined above is to insert code 
immediately before and immediately after 
the execution of a routine in a different 
language. This code alters the environment 
and, where necessary, sets up dummy 
aggregate arguments to and from which the 
values can be assigned. The handling of 
the environment is done by three 
interlanguage housekeeping routines that 
are held in the resident library. Data 
aggregates are handled by compiled code. 
Figure 13.1 illustrates the basic 
principles. 

The interlanguage facilities allow any 
number of calls to be made, and calls to 
both COBOL and FORTRAN routines can be made 
in the same program. Thus PL/I can call 
COBOL that calls PL/I that calls FORTRAN; 
FORTRAN can call PL/I that calls COBOL, and 
so on. All calls must, however, be made 
either to PL/I or from PL/I. Calls cannot 
be made directly between COBOL and FORTRAN. 
Options allow the programmer to specify 
that PL/I interrupt-handling facilities 
will be available through the COBOL or 
FORTRAN routines for those program checks 
that are not handled by COBOL or FORTRAN, 
and also allow the programmer to specify 
whether he wishes data aggregates to be 
automatically re-formatted when passed as 
arguments. (The programmer may wish to 
carry out the re-formatting himself.) The 
rules involved are fully described in the 
language reference manual. Briefly, they 
are as follows. For a PL/I procedure to 
call a COBOL or FORTRAN routine, the name 
of the routine must be declared as an 
external entry point with the option COBOL 
or FORTRAN in the OPTIONS attribute. If 
the programmer wishes to take advantage of 
the PL/I error-handling or interrupt- 
handling facilities, the INTER option must 
be included in the declaration. When a 
PL/I procedure is to be called by COBOL or 
FORTRAN, the keyword COBOL or FORTRAN 
should be included in the OPTIONS option of 
the PROC or ENTRY statement. To override 
the creation or remapping of dummy 
arguments for aggregates when calling 
FORTRAN or COBOL, or to override the 
creation or remapping of dummy parameters 
when being called from FORTRAN or COBOL, 
the MOMAP, NOMAPIN, and NOMAPOUT options 
can be used. 

The compiler also allows the 
specification of the COBOL option in the 
ENVIRONMENT attribute of a PL/I file. This 
is separate from the interlanguage 
facilities described above, and is a method 
of allowing data sets produced by programs 
of one language to be used by programs of 
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SOURCE LISTING 



P13P2:PRGC; 

DCL FRED DPTiaNS(CQBDL) , 
1 STRUCTURE, 

2 C CHAR (lit 
2 D FIXED BINARY (31,0)! 
CALL FREO(STRUCTURE); 
END; 



OBJECT LISTING 



* STATEMENT NUMBER 
00CC6A 41 00 0C8 

58 10 D 04C 

IE CI 

55 cc c ;oc 

47 DO 2 0]8 
58 FC C 048 
05 EF 



000C6E 
000072 
000074 
000078 
C0C07C 
0CCC8C 
0CC08 2 
0C0082 
0CC086 
0C0C8A 
O00C8E 

000094 
0C0C98 

00C09E 
CO0OA2 
003CA6 
OCDCAA 
OCCOAC 
OOOGAE 
OO0CB2 
0CCCB6 
CO0OB8 
003CBC 
OOOOCC 
CC0OC2 
00C0C4 
0000C8 
OCOOCA 



50 00 
41 11 
50 10 
D2 C3 



04C 
OOC 
0A8 
088 



58 80 D C88 

02 C3 1 OOC D C88 

58 70 D 0B4 

50 70 1 004 

58 FO 3 OOC 

18 91 

05 EF 

50 9C 

96 80 

IB 55 

41 1C 3 030 

58 FC 3 034 

18 69 

05 EF 

58 FO 3 CIO 

05 EF 

D2 03 D 088 



C3C 
C3C 



OOOODC 58 FC D 088 
00CCD4 D2 C3 D CB3 D C88 



OOOCDA 58 60 9 004 
COCCDE 50 6C D CB4 



LA 

L 

ALR 

CL 

BNH 

L 

BALR 

EQU 

ST 

LA 

ST 

MVC 



MVC 

L 

ST 

L 

LP 

BALR 

ST 

01 

SR 

LA 

L 

LR 

BALR 

L 

BALR 

MVC 

L 
MVC 



0,8(0,0) 

1,76(0,13) 

0,1 

C, 12(0, 12) 

CL.4 

15,72(0,12) 

14,15 

* 

0,76(0,13) 

1,0(1,01 

1,168(0,13) 

WKSP. 1+16(4), STRUC 

TURE.C 

8,WKSP.1+16 

STRUCTURE-179(4),M 

KSP.1+16 

7, STRUCTURE. D 

7,4(C,1) 

15,A..IBMBIECA 

9,1 

14,15 

9,48(0,3) 

48 ( 3 1, X' 80' 

5,5 

1,48(0,3) 

15,52(0,3) 

6,9 

14,15 

15.A..IBMBIECC 

14,15 

WKSP. 1+16(4), STRUC 

TURE-179 

15.WKSP.1+16 

STRUCTURE. C(4) ,WKS 

P. 1+16 

6,4(0,91 

6, STRUCTURE. D 



Get VDA for dummy 
arguments 



Place new value in NAB 



► Move structure into dummy 



Branch to interlanguage 
housekeeping routine 

Set up 
argument list 



Branch to COBOL routine 
Branch to interlanguage 
housekeeping routine 

Move values from dummy to 
'real arguments 



Figure 13.2. Typical code when PL/I calls COBOL or FORTRAN routine 



the other lanquage. The use of the COBOL 
option in the ENVIRONMENT attribute is 
described in the last section of this 
chapter. 



housekeeping routine to save the PL/I 
environment and prepare for the other 
program. 



PL/I Calls FORTRAN or COBOL 



| 4. Call the required COBOL or FORTRAN 

| routine passing a parameter list which 

I does not use locators. 



When the calling program is PL/I, the 
compiler generates in-line code and library 
calls to handle the environment and data 
aggregate problems and places the code 
before and after the call to a program of a 
different language. The order of events 
is: 

1. Re-arrange data aggregate arguments, 
if necessary, by creating and 
initializing a dummy of the correct 
format. u 

2. Call the appropriate interlanguage 



4. Call the interlanguage housekeeping 
routine to restore the PL/I 
environment. 



5. If necessary, assign the values of the 
dummy data aggregate to the PL/I data 
aggregate. 

6. Continue processing in the normal 
manner. 

A typical code sequence illustrating the 
above process is shown in figure 13.2. 
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Encompassing procedure called by COBOL or FORTRAN 



Save calling environment. 

Establish PL/I environment. 

Set up dummy data aggregate parameters, if necessary. 

Call required procedure. 

Required procedure 



Carry out required tasks in PL/I environment 
established by encompassing procedure. 



Assign values of dummy data aggregates to correct aggregates. 
Restore environment of calling program. 



Figure 13.3. Nested procedures used when COBOL or FORTRAN calls PL/I 



FORTRAN or COBOL Calls , PL/I 



When PL/I is called from another language, 
the method used is different. The code to 
handle environment and data aggregate 
problems cannot be included in the calling 
program, as this has been compiled in the 
normal manner by a COBOL or FORTRAN 
compiler. Instead the code is placed in 
the called program. This is done by the 
compiler generating two nested PL/I 
procedures. The outer procedure is the one 
that is actually called by the other 
program. It carries out the housekeeping 
duties, calling the interlanguage 
housekeeping routines to set up or restore 
the PL/I environment, and producing 
suitable dummy aggregate parameters if 
necessary. The inner procedure is compiled 
in the normal manner, called by the outer 
procedure, and executes the object code 
corresponding to the PL/I program. 
Throughout this chapter the outer procedure 
is called the encompassing p rocedure and 
the inner procedure the required procedure. 
The system of nested procedures is 
illustrated in figure 13.3. 



Throughout the remainder of this 
discussion, the first procedure entered in 
a job or jobstep, which would be known in 
PL/I as the main procedure, is referred to 
as the pri ncipal procedu re. This is 
because there is no COBOL or FORTRAN term 
equivalent to "main procedure" in PL/I. 

When PL/I is called from COBOL or 
FORTRAN, the PL/I environment may already 
have been set up and may need restoring 
from the information that has been saved. 
This can happen in two circumstances. 

1. The principal procedure in the job or 
jobstep may have been a PL/I main 
procedure which called FORTRAN or 
COBOL, which in turn called PL/I, 

2. There may have been a previous call to 
PL/I in a job or jobstep whose 
principal procedure is in COBOL or 
FORTRAN. In this situation, the PL/I 
environment is retained until the 
calling routine itself is completed. 
This speeds execution of other calls 
to PL/I routines. 

When the PL/I environment has already 
been established, it can be restored by 
pointing registers 12 and 13 at the TCA and 
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Encompassing routine compiled with ESD reference to PAYROLL 

Save registers of calling routine 

Call interlanguage housekeeping routine 

Interlanguage housekeeping routine (entry point IBMBIEPA) 



Call PL/I initialization routine IBMDPIR, if PL/I environment not set up 
IBMDPIR - PL/I initialization routine 



Set up TCA etc. 

Issue STXIT macro instruction to initialize PL/I error handling 



Acguire DSA for encompassing routine PAYROLL 

Rearrange chaining of save areas 

Produce dummy data aggregate of correct format if necessary 

Return to encompassing routine 



Call PAYROLL 

PAYROLL (procedure reguired by calling program) 

I Functioning in normal PL/I environment, so no special coding required 

Call interlanguage housekeeping routine 

Interlanguage housekeeping routine (entry point IBMBIEPC) 

Issue STXIT macro instruction to restore calling program's error-handling mechanism 

Assign values in dummy data aggregate to correct data aggregate. 

Return to calling routine 

Figure 13.4. Action when setting up PL/I environment on call from COBOL or FORTRAN 
principal procedure 



the current DSA respectively, and resetting 
the program check exit and program mask so 
that program checks are passed to the PL/I 
condition- handling modules. However, on 
the first call in a program with a 
principal procedure in COBOL or FORTRAN, 
the PL/I environment must be completely 
initialized. This involves acquiring 
storage for the program management area and 
for dynamic storage allocation. This 
storage is known as the ISA (initial storage 
area) and is described in chapter 6. 



The area used for the ISA will be that 
part of the partition that is not taken up 
by the executable program phase, unless an 
area has been assigned, in either a COBOL 
or FORTRAN routine, by use of a call to 
PLISA. (PLISA is described later in this 
chapter.) Space is also allowed in the 
high-address end of the partition for the 
DTF and buffers for SYSLST. 

Seq uence of Events when PL/I is called..frpm 
FORTRAN or COBOL; When PL/I is called from 
FORTRAN or COBOL, the routine that gets 
control is the encompassing PL/I routine. 



This routine is given the name of the 
procedure called from COBOL or FORTRAN, and 
appropriate ESD references are generated. 
The subsequent sequence of events depends 
on whether or not the PL/I environment has 
been previously initialized. The sequence 
is given below and illustrated in figures 
13.4 and 13.5. 



1. The encompassing routine is called by 
COBOL or FORTRAN and: 

a. Saves the registers of the calling 
program. 

b. Calls the interlanguage 
housekeeping routine, passing the 
interlanguage routine the sire of 
the DSA that the encompassing 
routine itself will require. 

2. The interlanguage housekeeping routine 
then: 

a. Tests to see if the PL/I environ- 
has been established previously 
and can be restored. 
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b. If possible, restores the PL/I 
environment and returns to the 
encompassing routine. 

c. If the PL/I environment has yet to 
be initialized, the housekeeping 
routine calls IBMDPIR, passing it 
an address in the interlanguage 
housekeeping routine, to which 
control will return. Control 
blocks are set up to handle the 
housekeeping problems. Save areas 
are rechained so that the save 
area of IBMDPIR (dummy DSA) comes 
before the save area for the COBOL 
or FORTRAN calling program. 
Consequently, the PL/I environment 
will not be lost until the calling 
program itself is finished. 
Module IBMDIEP inserts a short 
save area and an interlanguage 
save area, and IBMDPII creates a 
dummy DSA, all of which are left 
in the DSA chain (see figure 
13.5). These save areas are 
specially created and used to 
return control to the 
interlanguage housekeeping routine 
before and after the execution of 
IBMDPIR on termination. Control 
is then returned to the 
encompassing procedure. 

3. The encompassing procedure reformats 
data aggregate arguments if necessary, 
sets up locators where they will be 
expected by PL/I, and calls the 
reguired PL/I routine. 

4. The required PL/I routine carries out 
the required operations and returns 
control to the encompassing procedure. 

5. The encompassing procedure reassigns 
the data aggregate arguments, if any, 
and calls the interlanguage 
housekeeping routine. 

6. The interlanguage housekeeping module: 

a. Saves the PL/I environment. 

b. Restores the environment of the 
calling program. 

7. Control is returned to the 
encompassing routine, which, in turn, 
returns control to the original 
FORTRAN or COBOL calling procedure. 



to indicate which environments have been 
established, and to save environment and 
interrupt information. 

1. IBMBILC1 A control section included in 

each interlanguage 
housekeeping routine. The 
control section consists of 
two words. The first word 
contains a pointer to ZCTL(see 
below) . The second word 
contains three flags: COBOL 
and FORTRAN flags indicate 
whether the COBOL or FORTRAN 
environment has been set up 
and still exists; the third 
flag is a stack flag which 
indicates whether a call has 
been made to PLISA to indicate 
where the ISA should be 
placed. 

2. ZCTL A control block generated on 

the first interlanguage call 
and retained until the PL/I 
environment is discarded, or 
until the end of job. ZCTL is 
set up in the high-address end 
of the area used for the ISA. 
It is set up as non-LIFO 
dynamic storage when PL/I 
calls FORTRAN or COBOL. When 
PL/I is called from COBOL or 
FORTRAN, ZCTL is set up before 
any of the PL/I eftvironment is 
established; however, it is in 
the position that would be 
occupied by non-LIFO dynamic 
storage, although it is not in 
the ISA. 

3. Interlanguage VDA 

This is a control block that 
is generated in a VDA in the 
LIFO stack for every call to 
COBOL or FORTRAN, or 
initializing call to PL/I. It 
is used to retain register 13 
and to retain COBOL and 
FORTRAN interrupt information 
during the execution of nested 
calls. 

Figures 13.6 and 13.7 show how these 
control blocks are used in a series of 
interlanguage calls that start from PL/I 
and FORTRAN principal procedures 
respectively. 



CONTROL BLOCKS IN INTERLANGUAGE 
COMMUNICATION 



SPACE FOR PL/I DYNAMIC STORAGE AND 
PROGRAM MANAGEMENT AREA 



Three control blocks are used during 
interlanguage communication. They are used 



Unlike FORTRAN or COBOL, PL/I requires 
space for dynamic storage allocation and 
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SAVE AREA CHAINING 






Standard save area of outer 
procedure/calling routine (if any) 






— ► 


COBOL or FORTRAN calling routine save area 






4 




Short save area 


^ 


fe 








^ 


Interlanguage routine save area 
(Save area 2 in ZCTL) 


^ 




w 


PL/I initialization routine save area 








^ 


PL/I encompassing procedure save area 


^ 














PL/I required procedure save area 









© 



© 



© 



© 



© 



© 



© 



Rearrangement of save area chaining takes place after the 
first call to PL/I, so that the PL/I environment is not discarded 
until the calling routine itself is finished. 

Save areas that return control to the PL/I initialization routine 
and interlanguage housekeeping routine are placed before the 
calling routine. (The numbers 1-7 in the diagram show the 
order of backchaining). 



Figure 13.5. Chaining of save areas when PL/I is called from COBOL or FORTRAN 
principal procedures. 
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for a program management area. These areas 
are an important part of the PL/I 
environment and are set up during 
initialization of the ISA. 

The default action of the PL/I 
initialization routine is to set up the ISA 
in that part of the partition that is not 
taken up by the executable program phase, 
allowance being automatically made for a 
buffer and a DTF for SYSLST. Consequently, 
there is no need to call PLISA if only 
SYSLST is used for I/O by FORTRAN. 
However, the programmer in FORTRAN or COBOL 
has a method of overriding this action by a 
call to PLISA. In the call to PLISA, a 
FORTRAN or COBOL variable must be named and 
a length given. The ISA will then be set up 
at an address starting at the first 
doubleword in the variable, and taking up 
an area large enough to hold the specified 
length starting on a doubleword. This 
length should not be greater than that of 
the variable, or other parts of the COBOL 
or FORTRAN program will be overwritten by 
the ISA. 

This facility is necessary because 
FORTRAN I/O buffers use space outside the 
executable program phase and can 
consequently overwrite or be overwritten by 
the ISA. However, when the area to be used 
for the ISA is included in the executable 
program phase, as it will be if a FORTRAN 
or COBOL variable is used, the area will be 
automatically protected from overwriting. 
The facility is available in COBOL 
programs, since these programs may call 
PL/I, which may in turn call FORTRAN. 
Since the ISA is set up on the first call 
to PL/I, the problem of overwriting with 
FORTRAN buffers arises in this situation, 
unless the area is specified before the 
first call to PL/I. 

A call to PLISA goes to a section of the 
interlanguage housekeeping routine of which 
PLISA is an alias. This routine sets a 
flag in IBMBILC1, to indicate that an area 
has been designated for the ISA, and alters 
a parameter list for IBMDPIR in such a way 
that the length and address of the largest 
area that can be bounded with doubleword 
boundaries inside the declared length are 
placed in the parameter list. 

When the PL/I interlanguage housekeeping 
routine IBMDIEP is called, it tests to see 
if the stack flag is on. If the flag is 
on, the ISA is set up in the area 
designated in the PLISA call. 



Handling Changes of Environment 



Because the environments reguired for the 



various languages differ, they are handled 
by three distinct library modules. These 
modules are known as interlanguage 
housekeeping modules. 

Three modules are involved in the 
management of housekeeping during 
interlanguage communication. 

1. IBMDIEC: COBOL when called from PL/I 

2. IBMDIEF: FORTRAN when called from PL/I 

3. IBMDIEP: PL/I when called from FORTRAN 

or COBOL. 

Each module has a number of entry points to 
deal with various situations, and each is 
called immediately before and immediately 
after the program that is required. 



COBOL WHEN CALLED FROM PL/I (IBMDIEC) 



When calling COBOL, IBMDIEC carries out the 
following tasks: 



Before , Entry to COBOL Program 
(IBMBIECA, IBMBIECB), 



1. Test to see if this is the first 
interlanguage call; if so, set COBOL 
flag in IBMBILC1 and set up ZCTL. 

2. Acquire interlanguage VDA and store 
register 12 in ZCTL, register 13 in 
the VDA. Write null (zero) error 
information in ZCTL. 

3. If INTER option not specified (i.e., 
entry point IBMBIECA) , issue STXIT 
macro instruction and set program mask 
so that errors will be handled by the 
supervisor. Return to compiled code. 

4. If INTER option is specified (entry 
point IBMBIECB) , issue new STXIT macro 
instruction and return. 



On Return from COBOL Program (IBMBIECC) 



The following actions take place on return: 

1. A STXIT macro instruction is executed, 
which results in the program check 
exit being set to pass control 
directly to the PL/I interrupt 
handler. sis 

2. The first word of the interlanguage 
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1 



Initial situation 

IBMBI LCI is set up as a control section by pe PL/I interlanguage 
routines: Its first word and flags are initially zero. 



IBMBILC1 



Zero 



Zero 



Zero 



\- J ~t 



COBOL FORTRAN 
flag flag 



IBMBILC1 



ZCTL 



Address of ZCTL 



IBMBILC1 



ZCTL 



VDA (First) 



Call FORTRAN from PL/I (IBMBIEF) 

The compiler generates a call to the interlanguage communications 

routine. This routine: 

1. Sets up ZCTL after testing for zero pointer in IBMBILC1. 
Acquires an interlanguage VDA. 

2. Sets ZCTL pointer to interlanguage VDA, and IBMBI LC1 
pointer to ZCTL. 

3. Sets FORTRAN flag in IBMBILC1. Saves R12 in ZCTL, 
R13 in interlanguage VDA. 

4. Calls FORTRAN library to initialize FORTRAN SPIE 

5. Resets program check exit as required. 

6. Returns to compiled code, which calls FORTRAN 
procedure. 



~y 



X 



s* 



FORTRAN 
interrupt handling 
information 



R12 





R13 




'%$$§^^$$M#!^M$$^. 


. 





Call PL/I from FORTRAN (IBMBIEP) 
The PL/I program, because it is declared with the option 
FORTRAN, will have been compiled inside an encompassing 
procedure. The encompassing procedure is the one called by 
FORTRAN. The encompassing procedure calls the inter- 
language communications routine IBMBIEP, which: 

1. Checks IBMBI LC1 to see if either FORTRAN or COBOL 
flag is set. As one flag is set, restores registers. 

2. Issues PL/I SPIE and STAE and stores interrupt handling 
information of calling program in interlanguage VDA. 

Control tnen returns to the encompassing program, which calls 
the required PL/I program. 



IBMBILC1 



ZCTL 



VDA (First) 



~y 



X 



FORTRAN 
interrupt handling 
information 



R12 



R13 



FORTRAN 
interrupt handling 
information 



Call COBOL from PL/I (IBMBIEC) 

The PL/I program will contain a call to the interlanguage routine 

IBMBIEC, which: 

1. Sets up another interlanguage VDA, points ZCTL to this 
VDA, and places the old value of ZCTL's pointer in the 
VDA. 

2. Stores R13 in the new VDA. 

3. Issues a SPIE so that error handling will be as requested 
by PL/ 1 program. 

Control is then returned to compiled code, which then calls 
the COBOL routine. 



IBMBILC1 



ZCTL 



VDA (Second) 



VDA (First) 



X X 




Figure 13.6. Example of chaining sequences (PL/I principal procedure) 
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m Final situation 

^ ZCTL is retained until program is completed. 
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FORTRAN returns to PL/I (IBMBIEF) 

When control returns from a FORTRAN procedure, a call is made 
to the interlanguage communication routine IBMBIEF, which: 

1 . Moves the pointer in the VDA to the first word of ZCTL. 

2. Issues a PL/I SPIE macro. 

3. Issues a PL/I STAE macro leaving the previously-stacked 
FORTRAN STAE for possible future use. 

4. Returns control to compiled code. 
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PL/I returns to FORTRAN (IBMBIEP) 

When the required PL/I procedure is finished, it returns control 
to the encompassing procedure. The encompassing procedure 
calls the interlanguage routine IBMBIEP, which issues a SPIE 
macro instruction to restore the error-handling situation to that 
of the calling routine. The information for the SPIE macro 
instruction is retrieved from the interlanguage VDA. The 
current PL/I STAE is canceled, leaving the previously stacked 
FORTRAN STAE in control. 

The interlanguage routine returns control to the PL/I encompas- 
sing procedure, which then returns control to the FORTRAN 
program. 
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COBOL returns to PL/I 

The COBOL program returns to the PL/I program, which 
immediately calls the interlanguage routine IBMBIEC. This 
routine rearranges the chain by placing the word in the most 
recent VDA in the first word of ZCTL. It then issues a SPIE 
macro instruction to restore the PL/I error-handling situation. 

PL/I compiled code then continues. 
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FORTRAN principal procedure calls PL/I 
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Figure 13.7. Example of chaining sequences (FORTRAN principal procedure) 
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VDA is moved into the first word of 
ZCTL, and the VDA is freed. 



Actio.n._on_Interrupt i ..in COBOL 



If the INTER option is not specified, all 
program checks will be handled by the 
supervisor or the COBOL library. However, 
if the INTER option is specified and the 
COBOL program has been compiled with a 
reguest for the COBOL interrupt handler not 
to be called, the following takes place. 

1. During the first invocation of 

IBMDIEC, a STXIT macro instruction is 
issued, which results in interrupts 
being passed to an entry address in 
IBMDIEC. 



2. A further STXIT macro instruction is 
issued altering the program check exit 
to a further point in IBMDIEC. An 
interrupt is then caused and control 
passed through the supervisor to the 
new interrupt address. The reason for 
this is that the program in which the 
error occurred expects all registers 
to be restored, and this can only be 
done if return is made by the LPSW 
instruction. This is eventually 
caused by the EXIT macro. The address 
of the interrupt, taken originally 
from the second word of the PSW, is 
then restored to the PSW which has 
been saved in the area nominated by 
the STXIT macro instruction. The 
COBOL registers are restored to the 
interrupt save area. The program 
check exit is altered by a further 
STXIT macro instruction to IE007- 



When an interrupt occurs, register 12 
is restored from ZCTL and register 13 
from the interlanguage VDA, thus 
restoring the PL/I environment. 

A DSA is acguired for IBMDIEC in LWS. 
The address of the interrupt, in the 
second word of the PSW, is saved in 
this DSA and replaced by the address 
of another entry address in IBMDIEC. 
For underflow interrupts, the four 
bytes preceding the point of interrupt 
are also copied and placed before the 
entry address in case the error 
handler needs to examine them. This 
point acts as the return address for 
the PL/I error handler. 

Flags are set in the TCA and DSA to 
indicate that it is possible for an 
abnormal GOTO to occur in a PL/I on- 
unit. 

A STXIT macro instruction is issued to 
transfer the program check exit to the 
PL/I error-handling routines whose 
address is held in the TCA appendage. 

An interrupt is then caused, and 
control is passed to the PL/I error- 
handling routines by the supervisor. 



Return from Interrupt 



If a normal return to the point of 
interrupt is made, the following takes 
place. 

1. When the PL/I error-handling routines 
return control to what they take to be 
the point of interrupt, control in 
fact returns to an entry address in 
IBMDIEC. 



3. Control is returned to the supervisor 
by an EXIT macro instruction, which 
returns control to the point of 
interrupt. 

If, however, return occurs via the 
abnormal GOTO mechanism, IE015 branches to 
IE018, which unchains and frees the latest 
VDA and returns to the abnormal GOTO code. 



FORTRAN WHEN CALLED FROM PL/I (IBMDIEF) 



When FORTRAN is called by PL/I, the module 
IBMDIEF is entered immediately before and 
immediately after the execution of the 
FORTRAN program. The processing done 
before entry to the FORTRAN program depends 
on whether the INTER option is specified. 
Entry point IBMBIEFA handles calls without 
the INTER option. Entry point IBMBIEFB 
handles calls with the INTER option. 



Bef or e Ent ry to FORTRAN Program 
(IBMBIEFA and IBMBIEFB) 



Prior to the call to FORTRAN, IBMDIEF does 
the following: 

1. Tests the pointer in IBMBILC1 to 
discover if this is the first 
interlanguage call. If it is the 
first call, it sets up ZCTL and sets 
the FORTRAN flag in IBMBILC1* If it 
is not the first call, it tests to see 
whether the FORTRAN flag is set in 
IBMBILC1 and sets the FORTRAN flag if 
it is not already set. 

2. If the FORTRAN environment has riot 
previously been set up, calls the 



200 



6. 



FORTRAN initialization routine. This 
routine sets up the program check exit 
so that program interrupts will be 
handled by the FORTRAN error handling 
method. The FORTRAN error data is 
stored in ZCTL. 

Acguires an interlanguage VDA. Points 
the first word of ZCTL to this VDA, 
taking the value previously in the 
first word of ZCTL and placing it in 
the first word of the VDA. (This 
places the new VDA at the head of a 
chain starting from ZCTL.) 

Stores PL/I*s register 13 in the 
interlanguage VDA., thus saving the 
PL/I environment. 

If INTER option is not specified 
issues a FORTRAN STXIT macro 
instruction from ZCTL, sets program 
mask to '2', and returns to compiled 
code. 

If INTER option is specified, a STXIT 
macro instruction is issued that will 
result in control being passed to an 
entry address in IBMDIEF, should an 
interrupt occur. The program mask is 
reset to 'E' in case it was changed by 
the FORTRAN initialization routine. 



Action on Return from FORTRAN Program 
(IBMBIEFC and IBM BIEFD) 



When return is made from the FORTRAN 
subroutine, PL/I compiled code immediately 
makes a call to the FORTRAN interlanguage 
routine. If the FORTRAN routine may be 
used as a function, entry point IBMBIEFD is 
used. Otherwise, entry point IBMBIEFC is 
used. The module IBMDIEF does the 
following: 

1. A STXIT macro instruction is issued 
that resets the program check exit to 
the PL/I error-handling modules, and 
the program mask is set to , E'. 

2. The first word of the interlanguage 
VDA is placed in the first word of 
ZCTL and the VDA freed. 



Action on Interrupt in FORTRAN 



If the INTER option is not specified, the 
action on any interrupt that occurs in the 
FORTRAN program will be that specified in 
the FORTFAN error-handling scheme. 
However, if the INTER option is specified, 
all program checks that are not handled by 
FORTRAN error-handling are passed to the 
PL/I error-handling modules. 

The FORTRAN error-handling scheme is 
used after the following interrupts have 
occurred: 



1. Specification (other than for invalid 
instruction address) 

2. Fixed-point divide 

3. Decimal divide 

4. Exponent overflow 

5. Exponent underflow 

6. Floating-point divide 

All other program checks are handled by the 
PL/I error handler. 

When an interrupt occurs, the following 
talces place: 

1. When control is passed by the 
supervisor to an entry address, the 
type of interrupt is discovered by 
examining the PSW. If the interrupt 
is one of the types that can be 
handled by FORTRAN, the normal FORTRAN 
environment is established and the 
FORTRAN error handling module invoked. 

2. If it is not the type of interrupt 
that can be handled by FORTRAN, 
register 12 is restored from ZCTL and 
13 from the latest interlanguage VDA. 

3. The address of the interrupt is taken 
from the second word of the PSW and 
stored in the DSA. The second word of 
the PSW is then replaced by another 
entry address in IBMDIEF. 

4. Flags are set in the TCA and DSA to 
indicate that it is possible for an 
abnormal GOTO to occur in a PL/I on- 
unit. 



For entry point IBMBIEFD (the FORTRAN 
function entry point) the parameter 
list passed by PL/I is examined, and 
the values are moved out of the 
registers in which they were placed by 
the FORTRAN routine, and moved to the 
correct location. 



A STXIT macro instruction is then 
issued to restore the PL/I error- 
handling situation. A branch is then 
made to the PL/I error handler. 

For a normal return, the PL/I or 
FORTBAN error-handling routine returns 
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to the point of interrupt, which it 
takes from the second word of the PSW. 
This, in fact, is the entry address in 
IBMDIEF, which has been placed in the 
PSW in the PL/I interrupt save area. 
(See 3 above) 

7. If, however, return occurs via the 
abnormal GOTO mechanism, control 
passes to an address in IBMDIEF that 
unchains and frees the latest VDA and 
returns to the abnormal GOTO code. 

8. A STXIT macro instruction is issued to 
alter the program check exit to a 
third address in IBMDIEF. 

9. An interrupt is then caused, and the 
supervisor passes control to the 
program check exit address set in 8 
above. 

10. A further STXIT macro instruction is 
then given to restore the program 
check exit to the position at the 
start of the process. 

The method described in 7, 8, 9, and 
10 above is adopted as control has to 
be returned via the supervisor so that 
the values of all registers may be 
restored. 

11. The word originally taken from the PSW 
and stored in the DSA is restored to 
the PSW, which now holds the address 
of the point of interrupt. The 
FORTRAN registers are restored to the 
save area and an EXIT macro issued. 
This results in control returning 
through the supervisor to the point of 
interrupt. 



PL/I CALLED FROM COBOL OR FORTRAN 
(IBMDIEP) 



As with the other interlanguage 
communication routines, IBMDIEP is called 
immediately before and immediately after 
the program that is to be executed. 
However, the interlanguage housekeeping 
routine cannot be called direct from the 
COBOL or FORTRAN routine, because the 
existence of such a routine is unknown to 
COBOL or FORTRAN. To overcome this problem, 
an encompassing routine is generated with 
the same name as the PL/I routine. This 
encompassing routine is called by COBOL or 
FORTRAN and in turn calls the interlanguage 
housekeeping routine and the reguired PL/I 
routine. Code generated for a typical 
encompassing routine is shown in figure 
13.8. 

Although the names of both PL/I 



procedures are the same, the encompassing 
routine gets control when called from COBOL 
or FORTRAN, because no ESD records are 
generated for the interlanguage entry 
points of the required PL/I program. 



Before Entry, to PL/I program (IBMBIEPA) 



Before a call is made to the PL/I program, 
IBMDIEP does the following: 

1. Tests to see if the PL/I environment 
has already been initialized, by 
examining whether the COBOL or FORTRAN 
flag in IBMBILC1 is set. 

2. If the COBOL or FORTRAN flag is on, 
this means that a previous 
interlanguage call has been made, and 
as the call must have been made either 
to or from PL/I, the PL/I environment 
must have been set up. Register 12 is 
restored from ZCTL. A STXIT macro 
instruction is issued so that program 
checks are handled by the PL/I 
condition handler. 

The FORTRAN flag is set on and control 
returned to the PL/I encompassing 
procedure. 

3. If neither the COBOL nor the FORTRAN 
flag is on, PL/I is being called for 
initialization by a program whose 
principal procedure is in COBOL or 
FORTRAN. 

The following actions take place: 

a. IBMDIEP sets up ZCTL and then 
calls the initialization/ 
termination routine IBMDPIR to set 
up the PL/I environment. It 
passes the address of the storage 
to be used as an ISA. This is 
either the storage specified in a 
call to PLISA or the section of 
the partition between the 
executable program phase and an 
area allowed for the DTF and the 
buffer for STSLST. IBMDPIR is 
passed an address within IBMDIEP. 

b. IBMDPIR when completed makes a 
call to the entry point of IBMDIEP 
it was passed. This entry point 
saves the registers of IBMDPIR and 
rearranges the register save 
areas. The chaining of save areas 
is altered so that the save area 
that returns control to the 
initialization/termination routine 
IBMDPIR is placed above the save 
area of the routine that called 
the PL/I program. 
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c. The FORTRAN or COBOL flag is set 
depending on the language of the 
calling program. 

d. A DSA for the PL/I encompassing 
routine is acquired and its 
address returned to the 
encompassing routine. 

The encompassing procedure then 
points register 13 to its DSA, and 
after any necessary re-formatting 
of parameters calls the required 
PL/I routine. 

The order in which save areas are 
held starting with the oldest is: 

Caller's caller 

Save area two 

Dummy DSA (save area for 
IBMDPIR) 

Caller's save area (save area 
for COBOL or FORTRAN calling 
routine 

Short save area 

PL/I encompassing procedure DSA 

PL/I required procedure DSA 

A DSA for the encompassing routine is 
acquired. 



5. Control is then returned to compiled 
code in the encompassing routine. 

Action_after the PL/I Program is 
Completed (IBMBIEPC and IBMBIEPD) 



IBMDIEP is called at the end of the PL/I 
routine by the encompassing routine 
generated by the compiler. If the calling 
program is FORTRAN, a returned value may be 
expected in register or one or more of 
the floating-point registers. When this is 
the case, the entry point IBMBIEPD is used 
and the returned value is loaded into the 
required position. In other situations, 



the entry point IBMBIEPC is used. The 
module resets the program mask and issues a 
STXIT macro instruction to restore the 
calling routine's program check exit, the 
address of which has been stored in the 
interlanguage VDA. 



Interru pt Handling 

When PL/I is called by COBOL or FORTRAN, 
error handling is carried out in the normal 
PL/I manner. The STXIT macro instruction 
is issued by TBMDPII when the PL/I 
environment is first set up. For calls 
after the first, the STXIT macro 
instruction is issued by IBMDIEP. 



Handling Data Aggregate Arguments 



In order to communicate effectively between 
COBOL and PL/I, and FORTRAN and PL/I, a 
method of handling data aggregate arguments 
is necessary, because the three languages 
hold data aggregates in different ways. 



ARRAYS 



Arrays as such are not used in COBOL. .The 
use of OCCURS in structures does, however, 
have a similar effect. However, PL/T 
structures of arrays and COBOL structures 
using OCCURS are both held in row-major 
order. In FORTRAN, arrays are held in 
column-major order. Thus, in a two- 
dimensional array, the element known in the 
FORTRAN array as (2,1) will become (1,2) in 
the PL/I array. 



STRUCTURES 



Structures are not used in FORTRAN. In 
COBOL the aliqnment requirements are met 
differently from PL/I. Full details of the 
differences in mapping are given in the 
language reference mannual for this 
compiler. 



METHOD USED 



The method used in handling data aggregates 
is to create dummy arguments of the correct 
format and let the called routine use the 
dummy. The values in the dummy are then 
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OBJECT LISTING 

OOOOOO 
000007 

* INTERLANGUAGE PROCEDURE 



* REAL 
000008 
OOOOOC 
000010 
000014 
000018 
00001C 
000020 
000024 
000028 
00002A 
00002E 
000030 
000032 
000038 
00003C 
000040 
000046 
00004A 



ENTRY 
90 EC D OOC 
47 FO F 014 
00000000 
OOOOOOAO 
00000000 



58 30 
41 10 
58 00 
18 8F 
58 FO 
05 EF 
18 F8 
02 03 
58 10 
58 10 



010 
004 
OOC 



3 018 



054 
004 
018 



3 030 



D2 OB 078 1 000 
92 00 D 080 
05 20 



* PROCEOURE BASE 
00004C 5 8 90 078 
000050 50 90 3 038 
000054 58 80 D 07C 
000058 50 80 3 03C 
00005C 58 70 080 
000060 50 70 3 040 
000064 41 60 098 
000068 50 60 3 044 
00006C 96 80 3 044 
000070 IB 55 
000072 41 10 3 038 
000076 58 FO 3 008 
00007A 05 EF 
00007C 41 60 D 098 
000080 50 60 3 048 
000084 41 10 3 048 
000088 58 FO 3 01C 
00008C 05 EF 
00008E 58 00 004 
000092 58 EO OOC 
000096 98 2C 01C 
00009A 07 FE 

♦ ENO INTERLANGUAGE PROCEDURE 



DC C« P13P11« 
DC ALH6) 

P13P11 



STM 14,12,12(131 

B *+16 

DC AiSTMT. NO. TABLEI 

DC F«160' 

DC ACSTATIC CSECT) 

L 3,16(0,15) 

LA U4(0,0) 

L 0,12(0,15) 

LR 8,15 

L 15.A..IBMBIEPA 

BALR 14,15 

LR 15,8 

MVC 84(4, 13), 48(3) 

L 1,4(0,13) 

L 1,24(0,1) 

MVC 120(12, 13), 0(1) 

MVI 128(13), X f 00« 

BALR 2,0 



L 9,120(0,13) 

ST 9,56(0,3) 

L 8,124(0,13) 

ST 8,60(0,3) 

L 7,128(0,13) 

ST 7,64(0,3) 

LA 6,152(0,13) 

ST 6,68(0,3) 

01 68(3), X'BO' 

SR 5,5 

LA 1,56(0,3) 

L 15,A..P13P11 

BALK 14,15 

LA 6,152(0,13) 

ST 6,72(0,3) 

LA 1,72(0,3) 

L 15,A..IBMBIEPD 

BALR 14,15 

L 13,4(0,13) 

L 14,12(0,13) 

LM 2,12,28(13) 

BR 14 



Store registers 



Set R3 as static base 

Pass length required for DSA 
Retain entry point address 

Branch and link to interlanguage housekeeping routine 

Restore entry point address to RI5 
Set up on -unit flags 



Place parameters at head of temporary storage 
Set R2 as program base 



Point R9 at arguments 

Store in argument list 

Place address of full word in argument list 

for possible returns value 



Mark end of argument list 
Set static backchain to zero 
Point Rl at parameter list 

Branch and link to required procedure 

Pick up RETURNS value 

Store in static storage 

Point Rl at returns value 

Branch and link to interlanguage housekeeping routine 

Restore all registers except Rl (used for returns value) 
Return to caller 



Figure 13.8. Encompassing procedure to be called by FORTRAN 
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assigned to the original argument when the 
execution of the called program is 
completed. 

If the data aggregates are 
nonadjustable, the mapping will be done 
during compilation and both the PL/I and 
the COBOL or FORTRAN mapping are produced. 
If the data aggregates are adjustable, the 
mapping is done during execution. Before 
the execution of the call to a program in 
another language, the data is transferred 
into the correctly mapped aggregate, which 
will be held in PL/I temporary storage. 
The values are reassigned to the original 
data aggregate after execution of the 
program in the other language. 

The assignment of data between the dummy 
and the argument is done by compiled code. 



NOMAP, NOMAPIN, AND NOMAPOUT OPTIONS 



The NOMAP, NOMAPIN, and NOMAPOUT options 
can be used by the programmer to specify 
that data aggregates will not be remapped 
and placed in dummy arguments. 

When NOMAP is specified, or when both 
NOMAPIN and NOMAPOUT are specified, the 
dummy is not generated at all, and the 
structure or array is passed as it stands. 

When only NOMAPIN is specified, a dummy 
is created, but it is not initialized with 
the values of the aggregate being passed. 
However, on return from the COBOL or 
FORTRAN routine, the data in the dummy is 
placed in the data aggregate that is being 
passed. 

When only NOMAPOUT is specified, a dummy 
is created, and the data from the data 
aggregate is moved into the dummy. When 
control is returned to the calling program, 
however, the data from the dummy is not 
moved into the data aggregate that was 
passed. 



CALLING SEQUENCE 



When PL/I calls COBOL or FORTRAN passing 
data aggregates as arguments, the seguence 
of events is: 

1. Handle data reassignment to dummy by 
compiled code. 

2. Call interlanguage housekeeping 
routine. 

3. Call COBOL or FORTRAN routine. 



4. Call interlanguage housekeeping 
routine. 

5. Assign data in dummy to real argument, 
by means of compiled code. 

When eOBOL or FORTRAN calls PL/I, the 
seguence of events is: 

1. The COBOL or FORTRAN routine calls the 
encompassing PL/I routine. 

2. The encompassing PL/I routine: 

a. Calls the interlanguage 
housekeeping routine. 

b. Sets up the necessary dummy data 
aggregate argument by compiled 
code. 

c. Calls the required PL/I routine. 

d. Reassigns the data from the dummy 
by compiled code. 

e. Calls the interlanguage 
housekeeping routine. 

f. Returns to the original calling 
routine. 

It is necessary to make calls in this 
order, because the data mapping must be 
done in a PL/I environment. 



Main Storage Situation During 
Interlanguage Communication 



To help with debugging, some of the main 
storage situations that can occur during 
interlanguage situations are shown in 
figures 13.9 through 13.11. 



Options Assembler 



The optimizing compiler provides a facility 
to simplify calling assembler language 
routines from PL/I. This consists of 
setting up an argument list that contains 
the addresses of all items passed rather 
than the addresses of locators. 

When an entry point is declared as 
OPTIONS ASSEMBLER, argument lists passed to 
the entry point contain no locator 
addresses. The addresses of any areas, 
arrays, strings, or structures are passed 
directly in the parameter list. (For a 
call to a PL/I routine, the parameter list 
would contain the address of locators for 
these data types. This is because the 



Chapter 13: Interlanguage Communication 205 



called routine might reguire information on 
the length or bounds of the data and this 
is accessible through the locator. See 
chapter 4 for details.) 

The ASSEMBLER option does not provide 
facilities for automatically overriding 
PL/I interrupt handling, nor does it allow 
PL/I routines to be called from assembler 
language. If the programmer reguires these 
facilities, he must provide the necessary 
code himself. The COBOL option without the 
INTER option provides complete facilities 
for calling, or being called by, assembler 
routines. However, its use involves the 
overhead of calls to the PL/I library 
interlanguage communication routines. 

Full instructions on how to use PL/I 
with assembler language are given in the 
programmer's guide for this compiler. 



Cobol Option in the Environment 
Attribute 



A separate interlanguage communication 
facility offered by the compiler is the use 
of the COBOL option in file declarations. 
This option allows data sets created by 
COBOL programs to be read by PL/I programs 
and allows data sets to be created by PL/I 
programs in a format that is usable by 
COBOL programs. Interchange of data sets 
presents no problems, unless structures are 
used in the data set. If structures are 
used, their mapping may be different. (See 
above, under the heading "Handling Data 
Aggregate Arguments.") When structures are 
involved and the mapping is not known to be 
the same, both COBOL and PL/I structures 
are mapped, and compiled code transfers the 
data between structures immediately after 



reading the data for input, and immediately 
before writing the data for output. 

During compilation, the compiler 
examines the record variable to see if any 
structures are involved. If no structures 
are involved, no further action need be 
taken. If structures are involved, a test 
is then made to see if the mapping of the 
structure or structures will be the same in 
COBOL and PL/I. If the compiler can 
determine that the mapping will be the 
same, then no action is reguired. If the 
compiler cannot determine that the mapping 
will be the same or if the structure is 
adjustable, the structure will be mapped in 
both the PL/I and the COBOL format. 
Adjustable structures will be mapped during 
execution by the resident library 
structure-mapping routines. Other 
structures will be mapped during 
compilation. 

When re-formatting of data is necessary, 
the following actions take place when a 
record I/O statement involving a file with 
the COBOL option is executed. 

INPUT: 

The data is read into a structure 
which has been mapped using the 
COBOL mapping algorithm and 
assigned to a PL/I mapped 
structure. 

OUTPUT: 

Before the output takes place, the 
data in the PL/I structure is 
assigned to a structure mapped for 
COBOL. The output to the data set 
then takes place from the second 
structure. 

The data assignment is carried out by 
compiled code in all circumstances. 
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Figure 13.9. Main storage situation when PL/I main procedure calls FORTRAN 
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Main storage situation when PL/I main 

procedure calls FORTRAN, which in turn calls PL/I 
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Figure 13.11. Main storage situation when PL/I main procedure calls FORTRAN, 
which calls PL/I, which calls COBOL 
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BEGINNING OF PARTITION 



EXECUTABLE PROGRAM PHASE 



Compiled code 

All executable instructions 
generated by the compiler. 
Contents depend on source 
program . 



Library subroutines 

IBMDPIR - initialization routine 

(sets up TCA and other control 

blocks in program management 

area, then passes control to 

compiled code using address 

heldinPLIMAIN) 

IBMDERR - error and condition 

handling routine 

IBMDPGR - storage management 

routine 

Other routines, as necessary, 

for I/O conversions, etc. 

LIOCS data management routines 

(if required) 



Static storage (static internal and miscellaneous 
control sections) 



PLISTART- Initial entry point. 

Contains code to pass control 
to initialization routine IBMDPIR 



PLIMAIN - Contains address of 
main procedure 



Addresses of: 

Compiled code entry points 
External routines 
Library routines 
Controlled variables 
Static external variables 
External files 
Label constants 
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Control blocks: 

Symbol table vector 

Symbol tables 

Parameter lists for library calls 

Descriptors and locators 

DEDs (data element descriptors) 



File information: 

FCB (file control block) 

DTF (data management control block) 

EN VB (environment control block) 

OCB (open control block) 

Filename 



Diagnostic statement table 
Non-qualified ONCBs 
Constants used in program 



Static variables less than 8 bytes 
Static variables less than 2048 bytes 
Other static variables 



PROGRAM MANAGEMENT AREA 



BOS 



TCA 



Flags 



Segment No. 



Segment No. 



BOS 



EOS 



Address of TRT table 



Address of TCA appendage 



Address of save area for IBMDPGR 



Anchor for open-file chain 



Address of DFB 



Address of IBMBPGRD - VDA overflow routine 



Address of IBMBPGRA - Get non-LIFO storage 
routine 



Address of IBMBPGRB - Free non-LIFO storage 
routine 



Address of IBMBPGRC - DSA overflow routine 



Address of IBMDERR - Error and condition 
handling routine 



TCA Appendage 



TISA - Address of byte beyond ISA 



TLFE - Address of last free area 



Address of dummy DSA 



Address of 'get LWS' routine 



Address of load module chain 



TERA - Address of interrupt handler 



Dummy ONCA 

(ON communications area) 



Holds default values for PL/I 
condition built-in functions 



TRT table 



Trans late-and-test table for IBMDERR, used 
in error handling to test for relevant on-cells 



Diagnostic File Block (see appendix B) 



Contains information relating to the use 
of SYSPRI NT for the transmission of 
diagnostic messages 



Save area for IBMDPGR 



Used by storage management routines when 
new segment of storage is required 



Dummy DSA (Dynamic storage area) 



Contains DSA for initialization routine, 
backchain to calling routine's save area 
(if any), pointer to start of major free 
area (NAB), etc. 



LWS (first allocation) 



Flags 



Offset to ONCA 



Chainback 



Register save area 



Address of LWS 



Segment No. 



NAB 



Workspace (56 bytes) 



Flags 



Offset to ONCA 



Chainback 



Register save area 



Address of LWS 



Segment No. 



NAB 



Workspace (56 bytes) 



ONCA (see appendix B) 



Chainback (to dummy ONCA) 



Values of (or locators for) 
condition built-in functions 



Caller's STXIT options 



Save area for caller's STXIT program check 
options 
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LIFO STORAGE (Ty 



Main procedure DSA 



Chainback (to dummy DSA 



Save area for main 
procedure's registers 



Address of LWS 



Segment No. 



Automatic variables and te 
associated with the procedu 
of dynamic ONCBs (ON coi 



Subroutine DSA 



Chainback 



Register save area 



Address of LWS 



Segment No. 



Automatic variables and ter 
associated with subroutine, 



VDA 



Automatic variables of adju 
such library routines as are i 
in/first-out basis. Other itei 
LIFO storage that cannot b< 
during prologue code. 



cks: 

ibol table vector 

ibol tables 

jmeter lists for library calls 

criptors and locators 

Ds (data element descriptors) 



ation: 

J (file control block) 

: (data management control block) 

i/B (environment control block) 

3 (open control block) 

name 



statement table 
3d ONCBs 
sed in program 



jles less than 8 bytes 
>les less than 2048 bytes 
: variables 



IANAGEMENT AREA 



BOS 



EOS 



table 



appendage 



reafor IBMDPGR 



file chain 



BOS 



Address of DFB 



Address of IBMBPGRD - VDA overflow routine 



Address of IBMBPGRA - Get non-LIFO storage 
routine 



Address of IBMBPGRB - Free non-LIFO storage 
routine 



Address of IBMBPGRC - DSA overflow routine 



Address of IBMDERR - Error and condition 
handling routine 



TCA Appendage 



TISA - Address of byte beyond ISA 



TLFE - Address of last free area 



Address of dummy DSA 



Address of 'get LWS' routine 



Address of load module chain 



TERA - Address of interrupt handler 



Dummy ONCA 

(ON communications area) 



Holds default values for PL/I 
condition built-in functions 



TRT table 



Trans late-and-test table for IBMDERR, used 
in error handling to test for relevant on-cells 



Diagnostic File Block (see appendix B) 



Contains information relating to the use 
of SYSPRI NT for the transmission of 
. diagnostic messages 



Save area for IBMDPGR 



Used by storage management routines when 
new segment of storage is required 



Dummy DSA (Dynamic storage area) 



Contains DSA for initialization routine, 
backchain to calling routine's save area 
(if any), pointer to start of major free 
area (NAB), etc. 



LWS (first allocation) 



Flags 



Offset to ONCA 



Chainback 



Register save area 



Address of LWS 



Segment No. 



NAB 



Workspace (56 bytes) 



Flags 



Offset to ONCA 



Chainback 



Register save area 



Address of LWS 



Segment No. 



NAB 



Workspace (56 bytes) 



ONCA (see appendix B) 



Chainback (to dummy ONCA) 



Values of (or locators for) 
condition built-in functions 



Caller's STXIT options 



Save area for caller's STXIT program check 
options 
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LIFO STORAGE (Typical contents) 



Main procedure DSA 



Chainback (to dummy DSA) 



Save area for main 
procedure's registers 



Address of LWS 



Segment No. 



NAB 



Automatic variables and temporaries 

associated with the procedure, chain 

of dynamic ONCBs (ON control blocks), etc. 



Subroutine DSA 



Chainback 



Register save area 



Address of LWS 



Segment No. 



NAB 



Automatic variables and temporaries 
associated with subroutine, etc. 



VDA 



Automatic variables of adjustable extent; 
such library routines as are used on a last- 
in/first-out basis. Other items requiring 
LIFO storage that cannot be allocated 
during prologue code. 



W 



-4 



MAJOR FREE AREA 





NON-LIFO STORAGE (Typical contents) 






Transient library routine not 
released on a block or procedure 
basis e.g., I/O transmitter 






I/O buffer 


4 






^^^||j|l;^R|g;ARjA^ ' : ;;:;:; ; ; 


^ 






Based variable allocated during 
execution 




, fc 


Controlled variable 




w 







%mmw' : ^m : i ■ free area .- .-,- : • • -:? 

WWW'Mi r : -:. : : : - : '-:" , ' : ' ;, : " : ' s : ;; -^ -'k.': '-'i ■ 






Controlled variable 


TLFE 

4 




^ 




^^^KSfSSiwN^^/v! 


TISA 
4 



END OF PARTITION 



Appendix A: Principal Contents of Storage 211 



Appendix B: Control Blocks 



This appendix provides information on the 
format of the control blocks that Bay be 
used during the execution of a program 
compiled by the DOS PL/I Optimizing 
Compiler. Brief details of the function of 
each control block, together with when it 
is generated and where it can be located, 
are also given. 

Except where explicitly stated all 
offsets from the start of a block are byte 
offsets and are given in hexadecimal 
notation. 
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Area Locator/descriptor 



How Addressed From an offset from register 
3 known to compiled code. 



Function 



Holds the address and length of the area 
variable for passing to other routines or 
for execution time reference if the area 
has an adjustable length. 



A (AREA VARIABLE) 
LENGTH 



Address of area variable is the address of 
the area variable control block. 

Length is the total length including both 
the control block and the area variable. 



When, Generated 



As far as possible during compilation, 
necessary completed during execution. 



Where Held 



Static internal control section. 



If AREA DESCRIPTOR 



The area descriptor is the second word of 
the area locator descriptor. It is used in 
structure descriptors, when areas appear in 
structures, and in the controlled variable 
•description 1 field when an area is 
controlled. 
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Area Variable Control Block 



Function 



Used to control storage allocation within 
the area variable. 



When Generated 



Note: If there are free elements in the 
area variabte~7 they are headed by two 
words. The first wolrd gives the length of 
the element, the secjond word gives the 
offset to the next smaller free element. 
If there is no smaller free element, the 
second word is set to zero. 

Flag X*0' Area variable does not contain 
free elements. 
X' 1 • Area variable does contain 
free elements. 



When the area variable is initialized. 
This depends on the storage class of the 
area. 



Where Held 



How Addressed 



As a variable dependant upon storage class. 
At the head of the area variable. 



0| 
I 



FLAG 



UNOSED 



OFFSET OF END OF EXTENT (OEE) 



, 

8 | OFFSET OF LARGEST FREE ELEMENT (LFE) 



C\ ZERO CHAIN FIELD IF FREE ELEMENTS 
, 

10| 



Area variable 
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Aggregate Descriptor Descriptor 



Base Element 



Function 



Contains information needed to map a 
structure or an array of structures during 
execution. Used for structures that 
contain adjustable extents or the REFER 
option. See chapter 4. 



12 

r ' t 

0|1 |F ± | ALIGNMENT | LENGTH | 

, , 

2| Level I Pal Fa! DIM | 

L— . J 



When Generated 



As far as possible during compilation. 
Adjustable values are filled in during 
execution. 



where, 



Ft - *0*B Not last element in structure 



= • VB Last element in structure 



ghere.He^d 



Static internal control section. 



How Addressed 



By an offset from register 3 known to 
compiled code 



General Format 



An aggregate descriptor descriptor consists 
of a series of fullword fields one for each 
structure element and one for each base 
element in the structure. 



Structure Element 



1 2 

r — — - .— — — — — — —————————— n 

0|0 | Fj. | Offset to entry for containing | 

1 | | block | 
, , 

2| Level |F a |F 3 | DIN | 

L- J 



F a = •0 , B Not an AREA 

= «1'B An AREA 
F 3 = »0»B Not a BIT string 

= • 1»B BIT string 
OFFSET 



LEVEL 



DIB 



= .The offset within the 
aggregate descriptor 
descriptor to the entry for 
the containing structure. 
The offset is held in 
multiples of four bytes. 

= Logical level of identifier 
in structure 

= Real dimensionality of 
identifier 



ALIGNMENT = Alignment stringency 

Value (dec.) Heaninc 



LENGTH 






bit 


7 


byte 


15 


half-word 


31 


word 


63 


double-word 



= Length (in bytes) of data 

LENGTH is set to for strings 
and AREAS, whose length is 
held in descriptors 
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Aggregate Locator whe £ e_Heid 

Static internal control section. 



Fu n ction 



How Addressed 



Used to pass the address of an array or 

structure and its associated descriptor to By an offset from register 3 known to 

a called routine. Also to associate the compiled code. 

aggregate with its descriptor during o 4 

execution. r 7 

0| Address of data aggregate j 
, , 

4 1 Address of descriptor I 

When Generated i j 

During compilation. 
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Array Descriptor 



Function 



the RVO (relatives virtual origin) . This is 
followed by two words for each dimension of 
the array, containing the multiplier and 
high and low bound for each dimension. 



Contains information about the extent of an 
array and the number of its dimensions. 
For arrays of area variables or strings, an 
area or string descriptor is attached to 
the array descriptor. 

The array descriptor is used to pass 
information about an array to called 
routines, or to hold information about an 
array with adjustable extents. 



When Genera te d 



As far as possible during compilation. If 
the array has adjustable extents, it is 
completed during execution when the values 
are known. 



4 
8 
C 
10 





RVO 


(AO-VO) 










Mult 


iplier 








High 


bound 


I 


Low 


botind 






Multiplier 


2 






High 


bound 2 


I 


Low 


bound 


2 



etc. 



Note; Two full words containing 
multiplier and high and low bound are 
included for each array dimension 



Arrays of structures make use of 
structure descriptors to hold similar 
information. 



Where Held 



Static internal control section. 



RVO = Relative virtual origin, the 
distance between the virtual 
origin (VO) and the byte actual 
origin (AO) . Virtual origin is 
the point at which the element in 
the array whose subscripts are all 
zeros is, or would be, held. 
Actual origin is the byte address 
of the first element in the array. 



How Addressed 



By an offset from register 3 known to 
compiled code 



RVO is held as a bit value for 
arrays of unaligned non-varying 
bit strings, but otherwise as a 
byte value. 



High bound: The highest subscript in 
the dimension. 



Arr ays of Strings or Areas 



Low bound: The lowest subscript in the 
dimension. 



For arrays of strings or areas, the 
descriptors are completed by string or area 
descriptors concatenated to the array 
descriptor. String and area descriptors are 
the second word of string and area 
descriptor/locator pairs. 

For bit string arrays, the bit offset 
from the byte address is held in the string 
descriptor. 



General Format 



The first word in the array descriptor is 



Multiplier: The multiplier is the 

offset between any two elements 
marked by the change of subscript 
number in the dimension. 

For example for the array DATA (10,10), 
the multiplier for the first dimension is 
the offset between DATA (1,1) and DATA (2,1) 
etc. The multiplier for the second 
dimension is the offset between DATA (1,1) 
and DATA (1,2). The offset is measured from 
the start of the one element to the start 
of the next. 

Multipliers are byte values except for 
unaligned non-varying bit string arrays, in 
which case they are bit values. 
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Controlled Variable Block 



Where Held 



Function 



At the head of the c&ntrolled variable. 



To hold information about the controlled 
variable. 



When Generated 



When the variable is allocated. 




WORD 1 
WORD 2 
WORD 3 
WORD 4 



I 



10| 



A (Anchor word) 
LENGTH 



How Addressed 



The latest allocation is addressed from an 
anchor word which is held in static 
internal storage for internal variables and 
a>n. a separate control section for external 
variables. 
4 



8 | Chain back to previous allocation 
, 

C | Unused 



DESCRIPTION 
Field used for descriptor or 
locator/descriptor in certain 
circumstances, (see below) 



DATA 



H Address, held in anchor word 
< . 



LENGTH: 



CHAIN BACK: 



DESCRIPTION 



Length of the total allocation 
including the 4 words of the 
heading. 



Address of word 5 of previous 
allocation, set to zero if 
first allocation. 



If the item is one that 
reguires a descriptor/locator 
or a locator, this is placed 
at the head of the data. If 
the item is a structure or 
array and the extents are 
unknown at compile time, the 
descriptor will also be placed 
before the data. class. 



Thus for: 



STRINGS and AREAS, the 
controlled variable is headed 
by a locator/descriptor ^ 

STRUCTURES and ARRAYS, the 
controlled variable is headed 
by a locator . 

STRUCTURES and ARRAYS with 
ADJUSTABLE EXTENTS, the 
controlled variable is headed 
by a loc a to r followed by a 
de scrip tor. 

ALL OTHER DATA, the 
descri ption field is not used 
and the data itself starts at 
offset X»10« (16) 
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Data Element Descriptor (DED) 



Function 



Used to pass description of data elements 
to library conversion and stream I/O 
routines. 



When Generated 



During compilation. 



Where Held 



Static internal control section. 



How Addressed 



By an offset from register 3 known to 
compiled code. ° 



Format of DEDs 



All DEDs are headed by two bytes that 
indicate the data type. These two bytes 
are followed by as many bytes as are 
required to complete the description of the 
data. 

For arithmetic items, DEDs are completed 
by such items as scale and precision. For 
pictured items, a representation of the 
picture is included in internal form. 



General F ormat 



iFlag byte 1 I Flag bvte 2 | Further bytes 

I I I as 

I Defines data (Completes as | required 

jtype | definition j 

i | if necessary I 



Flag Byte 1 

Hex Value Data Type 



08 


FLOAT 


OC 


Free decimal (an 




internal form) 


10 


FIXED PICTURE BINARY 


14 


FIXED PICTURE DECIMAL 


18 


FLOAT PICTURE BINARY 


tc 


FLOAT PICTURE DECIMAL 


20 


non-VARYING CHARACTER 


24 


non-VARYING BIT 


28 


VARYING CHARACTER 


2C 


VARYING BIT 


30 


CHARACTER PICTURE 


40 


BINARY constant 


44 


DECIMAL constant 


48 


BIT constant 


50 


F/E Format 


54 


P Format (arithmetic) 


58 


A/B/P Format (character) 


5C 


C Format 


60 


X Format 


64 


COL Format 


68 


SKIP Format 


6C 


LINE Format 


70 


PAGE Format 


80 


LABEL 


84 


ENTRY 


88 


AREA 


8C 


TASK 


90 


OFFSET 


94 


POINTER 


98 


FILE 


9C 


EVENT 


Flag 


Byte 2 



Bits 081 = '00'B A-format item 

•01'B B-format item '10'B 
character picture format item 



Bit 2 = '0«B 
M'B 

Bit 3 = '0'B 
M'B 

Bit 4 = «0'B 
M'B 

Bit 5 = '0'B 
M'B 



fixed constant 
float constant 

not extended float 
extended float 

F-format/f ixed picture 
E-f ormat/f loat picture 

declared binary 
declared decimal 



If bits 4 and 5 = • 1 1 • B then DED is for 
character 



Bit 6 = •O'B 
M'B 



short precision 
lonq precision 



00 
04 



FIXED BINARY 
FIXED DECIMAL 



Bit 7 = 'O'B real or length specified (A 

or B format) p.r unaligned bit 
string 
M'B complex (also set if E, F, or 
P in C-format) or no length 
specified (A or B format) or 
aligned bit string 

All bits for which neither value is 
defined are set to '0'B 
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In ternal codes , for pictures 



Code 


Picture 


Code 
48 


Pi 


.ctu 


00 


9 




_ 


(t) 


04 


Y 




4C 


- 


(d) 


08 


Z 




50 


- 


(s) 


OC 


* 




54 


$ 


(t) 


10 


E 




58 


$ 


(d) 


14 


K 




5C 


$ 


(s) 


18 


T 




60 


/ 


(t) 


1C 


I 




64 


/ 


(d) 


20 


R 




68 


/ 


(s) 


24 


CR 




6C 




(t) 


28 


DB 




70 




(d) 


2C 


B 




74 




(s) 


30 


S 


(t) 


78 




(t) 


34 


s 


(d) 


7C 




(d) 


38 


S 


(s) 


80 




(s) 


3C 


♦ 




84 


V 




40 


+ 


<d) 








44 


♦ 


(s) 








(t) = 


terminal 








(d) = 


drifting 








(s) = 


static 








DED f< 


ar STRING 


Data 







Plag byte 1 = Hex 30 

The internal code for string pictures is 
as follows: 



Code 



Pic ture (hex) 



A 


00 


9 


04 


/ 


08 


• 


OC 


t 


10 


* 


14 


B 


18 


X 


1C 



L ± - length of field with insertion 
characters 

L a = length of field without insertion 
characters 



DED for PICTURE DECIMAL Arithmetic Data 



r 1 

| Flag byte 1 I .Flag byte 2 1 



DED for FLOAT Data 



r t 

I Flag byte 1|Flag byte|2 precisionl Unused | 

*. j 



DED for FIXED Data 



1 



r 

I Flag byte 1 I Flag byte 2 1 precision | scale | 
I I I 1/128 | 

i — — — 



DED for PICTURE STRING Data 



0| Flag | Flag I 
I Byte 1 | Byte 2 | 



4! 



I Picture in internal 
I form 



r — " ' ~ n 

0| Flag | Flag | Precision! Scale 
\ Byte 1 | Byte 2 | |Factor+128 



4|Length of|Length of|Flag | Flag 
I Picture IData |Byte 3 I Byte 4 



Picture in internal code 





Bit 





= 






Bit 


1 


= 


•1»B 
»0»B 


4 


Bit 


2 


= 


•1'B 


i 






= 


•0«B 


-1 
1 


Bit 


3 


= 


•1»B 


•j 






- 


•0'B 




Bit 


4 


= 


•1«B 
•0»B 




Bit 


5 


= 


«1«B 


4 






= 


•0»B 


l 












Bit 


6 


= 


•1»B 

•0»B 




Bit 


7 


= 





Flag byte 1 = Hex 14 or 1C 

Flag Byte 3 (describes the mantissa 
subfield) 



reserved; must be set to 
•P'B 

drifting S in subfield 
no drifting S in subfield 

drifting + in subfield 
no drifting ♦ in subfield 

drifting - in subfield 
no drifting - in subfield 

drifting $ in subfield 
no drifting $ in subfield 

total suppression in 

subfield 

no total suppression in 

subfield 

* in subfield 

no * in subfield 

reserved; must be set to 

• » B 
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Flag Byte 4 (describes the exponent 
subfield) 

Same format as Flag Byte 3. 



Note; After E or K r the next byte contains 
the number of digits in /the exponent. 

Scale... Factor 

The scale factor of a picture DED is the 

number of digit positions after the 'V* (0 

if there is no » V*) added to the number in 
the F specification, if any. 

Rule for setting, bit 5 in Flag Bytes 3 
and 4 



Bit 5 is set if no 9, Y, T, _I*- or E is 
present. This applies before any Z, S, 
etc. has been translated to a 9. 

Ruleg, for translating picture s into encoded 
pictur es 

1. Characters 9 r Y, E, K, T, I, F, CR, 
DB, B, and V are translated directly. 

2. Characters Z and * are translated 
directly if they do not follow a V. 
If either follows a V, it is 
translated into the code for character 
9. 

3. An S, + , -, or $ is translated to a 
static S, +, -, or $ if it is the only 
one of its kind in the subfield. 

4. If more than one S appears in a 
subfield, the S's are translated into 
drifting S's. 

Except when: 

a. It appears immediately before a Y, 
9, V, T, I or R. In this case it 
is translated into the code for a 
terminal S. 

b. It appears anywhere after a V. In 
this case it is translated into 
the code for a 9. 

The same rule applies for the +\ -, or 

$. 

5. A "/"# a ",», or a "." is treated as 
drifting, if: 

a. It is in a subfield containing 

either one or more Z or asterisk, 
or more than one +s, -s, or $. 



and if: 



it is translated into terminal 
form. 



DE D for, Program Control Data 







i : i 

{ Flag j Flag | 
| byte 1 | byte 2| 

L- . — I 



FORMAT DEDS - FEDS 



For meaning of flag bytes see above under 
Data Element Descriptors. 



DED for F and E Format Items (FED] 







2 3 4 5 



| Flag | Flag | W* | D \ X | 
| byte 1 | byte 2 | | | | 

i j 

Flag byte 1 = Hex 50 

W = total length of the format field 

D = number of decimal places 

X = precision + 128 for F-format number of 
significant figures for E-format 



DED_f or PICTURE Format A rithmetic I tem s 



1 



2 3 4 



r t 

I Flag | Flag | H (copy of DED as for| 
| byte 1 J byte 2 I jarith. picture | 

L- J 

Flag byte 1 = Hex 54 

W = total length of the format field 



DED for PICTURE Format C haracter Items 
JFEDL 







1 



2 3 4 



b. It is not immediately preceding a 
Y, 9, V, T, I, or R. In this case 



r — t 

| Flag \ Flag | W I copy of DED as for | 
jbyte 1 | byte 2 | | pictured character I 
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Flaq byte 1 = Hex 58 

W = total length of the format field 

PEP, for C. Format Items (FED), 



Flag byte 1 = Hex 60, 64 , 68, 6C or 70 

Parameter - length of item (X format) 
column number (COL format) 
number of lines to skip (SKIP 
format) 

line number (LINE format) 
omitted for PAGE format 



r " i 

I Flaq | Flag | W | FED for | FED for | 
| byte 1 | byte 2| | real part jimag. part | 

L ; J 



Flag byte 1 = Hex 5C 

Note: The complex bit (bit 7) in flag byte 
2 is set in both the real part and the 
imaginary part FED. 

ff = total length of the format field 



PEP for Control Forma t Items (FED) 



I Flag | Flag | parameter | 
I byte 1 | byte 2 | | 



PEP for STRING Format Items (FED) 



I Flag | Flag | length 
| byte 1 | byte 2 I 



Flag byte 1 = Hex 58 

The difference between A, B r and P 
(character) formats is given by bits and 
1 of flag byte 2. The length field may be 
omitted for A and B format items. 
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Diagnostic File Block (DFB) 



Function 



Holds information used by the error message 
routines. 



When Generated 



During program initialization. 



Ehere Held 



Program managment area. 



ll2]i.E^E§§§§d 

From Y. *40' in the 1CA 



AFLA 
ABTS 
ASPD 
AOCL 
A5DC 



Flags | Unused 
A (transmitter) 
A(SYSPRINT FCB) 
A (EXPLICIT OPEN) 
A (Improvised Sysprint DTF) 



t 

4 

8 

C 

10 

J 14 



AFLA_-_Flaas 



AWTO Bit 0=1 Messages going to operator's 

console 
ASNO Bit 1 = always 
ASCO Sit 2=1 SYSPEINT cannot be opened or 

open with unsuitable 

attributes. 
AFPF Bit 3=1 Force page 
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Dynamic Storage Area (DSA) 



10 

14 
18 
1C 
20 
24 
28 
2C 
30 
34 
38 
3C 
40 
44 
48 
4C 
50 
54 
58 
5C 
60 
64 
68 
6C 
70 
74 



I Flags 


( Offset | 


j Chain Back I 


I Unused I 


I Save area 


R 14 | 


I Save area 


R 15 | 


j Save area 


R | 


I Save area 


R1 I 


| Save area 


R2 I 


I Save area 


S3 | 


I Save area 


R4 | 


( Save area 


R5 | 


I Save area 


R6 ( 


I Save area 


R7 | 


| Save area 


R8 | 


I Save area 


R9 | 


I Save area 


R10 | 


j Save area 


R11 ( 


I Save area 


R12 | 


I A (LWS) I 


I Segment* | 


NAB | 


| Segment* | End 


of Prologue NAB j 


(Block-Enable Cell (Current-Enable Cell j 


I Static backchain ( 


I A(Pirst Static ONCB) I 


j A (most recent Dynamic ONCB in Block) | 


I Unused I 


I Unused I 


( Unused I 


| A(ONCELLS) I 


ICEXQ ( // | 


Flags 2 | I 



Function 



Holds housekeeping information, automatic 
variables, and temporaries for each block. 



When Generated 



During execution. Allocated by prologue 
code every time a new block is entered. 



Where Held 



In the LIFO storage stack. Certain library 
Routines have their DSAs in library 
workspace (LWS) . See below 



How Addressed 



Current DSA addressed from register 13. 
Chainback to previous DSAs from offset X 
•4«. 



Flags 








Bit 


= 



1 


DSA in LWS 
DSA 


Bit 1 


= 



1 


NO ON Cells 
ON cells 


Bit 2 


- 




1 


No Dynamic ONCBs 
Dynamic ONCBs 



Bit 3 



Always set to zero. 



Bits 4 and 5 

= 00 Procedure DSA 

01 Begin DSA 

10 Library DSA 

11 On DSA 

Bit 6 = Not a dummy DSA 
1 Dummy DSA 

Bit 7 = Flags 2 invalid 
1 Flags 2 valid 

Bit 8 = always zero 

Bit 9 = Do not restore NAB on GOTO 
1 Restore NAB 

Bit 10 = Do not restore Current-enable 
on GOTO 
1 Restore current-enable cells 
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Bit 11 = 

Bit 12 = 

Bit 13 = 

Bit 14 = 
Offset 



Callee cannot use this DSA 

1 Callee can use this DSA 

Not an EXIT DSA 

1 EXIT DSA 

No statement # table 

1 Statement # table available 

always zero 



If the DSA is in LUS, offset is the 
offset of the ONCA. Otherwise, this field 



is not used. 

Clip. 

Save area for flag byte 1 of the TCA. 
Used if DSA is an exit DSA. 

Flags 2 

Bit = 1 Last PL/I DSA 

Bit 1 = 1 Ignore DSA for SNAP 

Bit 3=1 Inter-language DSA after 

interrupt in FORTRAN or COBOL 
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Entry Data Control Block (Entry 
Variable) 



How Addressed 



Function 



Holds the addresses of the data item and 
its DSA- 



When Generated 



When the variable is allocated. 



Where Held 



Depends on the storage class of the data 
item. 



As a variable, dependant on storage class. 

4 

r "" ~ i 

| Address | 

, , 

4 | Address of statically containing | 
I DSA at time of assignment | 

i - — j 

Word 1: bit 0=0 Address of entry 

= 1 Address of location 
containing 8-char. 
EBCDIC name of entry 
point 

Word 2: bit always = 
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Environment Block (ENVB) 



Where Heia 



Function 



Holds addressed of information declared in 
the environment option 



In the static external control section for 
the file if file is external. Otherwise in 
the internal static control section. 



When Generated 



During compilation 

r' 



4 
8 
C 

10 
14 
18 
1C 
| 20 



NFLA | NFLB | 
Flags | Flags I 


Unused 




Address of blocksize 




(NBLK) 


Address of record size 


(NREC) 


Address of keyloc or 
(NLOC/NSTK) 


address of 


stacker 


A(BUFOFF) or A(KEYLENGTH) (NBOF/NKYL) 


A(INDEXAREA) 




(NXAR) 


A(ADDBUFF) 




(NABF) 


A(OFLTRACKS) 




(NOFL) 


A (PASSWORD string locator) 


(NPAS) 



How Addressed 



By an address contained in the FCB of the 
file. 



NFLA Flags 

Bit when set BLOCKSIZE field valid. 

1 when set RECORDSIZE field valid, 

2 when set KEYLOC field valid. 

3 when set BUFOFF field valid 

4 when set KEYLENGTH field valid. 

5 when set INDEX AREA field valid. 

6 when set ADDBDF field valid. 
7 when set OFLTRACKS valid. 

NFLB_f lags 

Bit Function (R) (read) 



Bit 1 Function (P) (punch) 
Bit 2 Function (W) (write) 

reserved 

when set STACKER field valid 

reserved 

when set PASSWORD field valid 

reserved 



The addresses held are the locations 
where compiled code will have placed 
the correct values for the current 
environment. 



Bit 


3 


Bit 


4 


Bit 


5 


Bit 


6 


Bit 


7 


Addresses 
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Event Table (EVTAB) 



How Addressed 



Function 



Used by WAIT module as workspace and to 
provide status information on associated 
event. 



Address known to WAIT module 



When Generated 



During execution. 



Where Held 



In LIFO storage. 



4 

r n 

| (see below) | WECB 

, , 

4 | Chain field through EVTABs | WECH 
, , 

8 | A (Event variable) | WAEV 

, , 

C |A(ECBLIST element) | WAEL 

L— — — — — -J 

WECB Bit set when event is complete Bits 
1-7 Not used in this implementation 
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Event Variable Control Block 



Function 



To hold information about the operation 
with which the EVENT has been associated. 



When Generated 



Depends on the storage class of the event 
variable. 



Where Held 



Depends on the storage class of event 
variable. 



How Address ed As a variable, dependand upon 
storage class. 



Flags 1 
Bit 

Bit 1 

Bit 2 

Bit 3 

Bit 4 



=0 Incomplete 
1 Complete 

=0 Inactive 
1 Active 

=0 Mot an I/O EVENT 
1 I/O EVENT 

=0 Not a DISPLAY EVENT 
1 DISPLAY EVENT 

=0 EV has not caused on-un it entry 
1 EV has caused entry to an 
on-unit 



Bit 7 =always zero 
Zlaas_2 
Bit 



No chain of ECBs 

1 Chain of ECBs exists 



Bit 1 =0 Not a dummy EVENT 
1 Dummy EVENT 



1 Flags'! | Flags2 | 
, 

I- 

8| 



STATUS 



Anchor for ECB chain 



A(ECB)/A(CCB) 



, 

C|A(TCA appendage for I/O) 
, 

10| 



A (FCB) 



14 | Not used 

L 
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File Control Block (FCB) 



Function 



Used to access all file information. 
Contains addresses of the ENVB, DTF r ACB, 
filename, etc. 



When Generated 



As far as possible daring compilation. 
Completed by the open routines during 
execution. 



Where Held 



In the static internal control section for 
internal files. 

In the associated file control section for 
external files. 



How. Ad dressed By an offset from register 3 
if internal. Address filled in by linkage 
editor if external. 



Common Section 



FFST Flags indicating types of statement 
(8 bytes) 



Bit number 


Statement ♦ options 





READ 


SET 


1 


READ 


SET KEYTO 


2 


READ 


SET KEY 


3 


READ 


INTO 


4 


READ 


INTO KEYTO 


5 


READ 


INTO KEY 


6 


READ 


INTO KEY NOLOCK 


7 


READ 


IGNORE 


8 


READ 


INTO EVENT 


9 


READ 


INTO KEYTO EVENT 


10 


READ 


INTO KEY EVENT 


11 


READ 


INTO KEY NOLOCK EVENT 


12 


READ 


IGNORE EVENT 


13 


WRITE FROM 


14 


WRITE ?ROHi KEYFROM 


15 


WRITE FROM EVENT 


16 


WRITE FROM KEYFROM EVENT 


17/ 
1B 


REWRITE 


REWRITE FROM 


19 


REWRITE FROM KEY 


20 


REWRITE FROM EVENT 


21 


REWRITE FROM KEY EVENT 


22 


LOCATE SET 



23 






LOCATE SET KEYFROM 


24 






DELETE 


25 






DELETE KEY 


26 






DELETE EVENT 


27 






DELETE KEY EVENT 


28 






UNLOCK KEY 


29- 


-63 




Reserved 


Common Section 







1 


2 






r i 

Flags showing valid statement types | 

(FFST) | 


8 


A (invalid statement module] 


(PAIS) | 


C 


A (library transmitter) 


(FATM) | 


10 


A (file name) 


(FNAM) | 


14 


A (environment block) 


(FENV) I 


18 


A(DTF)/A(ACB) (FDTF/FACB) | 


1C 


A (open file chain) 


(FAFO) | 


20 


FTYP | FER1 


FER2 | 


24 


FATA | FATB I FATC 


FATD | 


28 


FFLA | ; FFLE | FFLC 


FFLD I 


2C 


FFLE | FFLF | FFLG 


FFLH | 


30 


Blocksize (FBKZ) | FLOP 


FFLI | 


34 


Record length 


(FRCL) | 


38 


A (hidden buffer)/ 
A(IOCB) for VSAM 


(FREC) | 
(FAFR) | 


3C 


A (buffer space) 


(FIOA) | 


40 


Length of buffer space 


(FIOL) | 


44 


I I 

FEFA | FERA | 
I I 


48 


Unused (1 word) 





FTYP 6th and 7th characters of library 
transmitter name 

FER1 and FER2 Error Flags 

FATA-FATD Flags showing attributes 

allowable with file types, and 
other file usage information. 

Bit Attr ibute 

FATA (Open SYSPRINT for error 
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FATB 



FATC 



FATD 



FFLA 



FFLB 



FFLC 



FFLD 





message) 


1 


(SYSPRINT) 


2 


unused 


3 


(String operation) 


4 


unused 


5 


DISPLAY 


6 


RECORD 


7 


STREAM 





BACKWARDS 


1 


UPDATE 


2 


OUTPUT 


3 


INPUT 


4 


unused 


5 


unused 


6 


DIRECT 


7 


SEQUENTIAL 





unused 


1 


unused 


2 


unused 


3 


PRINT 


4 


unused 


5 


KEYED 


6 


UNBUFFERED 


7 


BUFFERED 


all 


unused 


[ Flags Bit 





F-format 


1 


V-f ormat 


2 


U-format 


3 


Spanned 


4 


Blocked 


5 


unused 


6 


unused 


7 


Key in record 




variable KEYLOC 





CONSECUTIVE 


1 


INDEXED 


2 


REGIONAL (1) 


3 


unused 


4 


REGIONAL (3) 


5 


unused 


6 


unused 


7 


other organization 




(see FFLI) 





LEAVE 


1 


UNLOAD 


2 


BUFFERS (2) 


3 


Permanent output error 




(mag. tape) 


4 


stacker (2) 


5 


associated file 


6 


3881 device 


7 


unused 





Transmitter 




deblocking 


1 


ERET macro 



permitted 

2 DTF completed by compiler 

3 buffer length calculated 
by compiler 

4 ENDFILE module loaded 

5 unused 

6 error module loaded 

7 GENKEY 



FFLE I/O error 

1 permanent input error or 
non-scalar varying, length 
set 

2 permanent output error 

3 end of file 

4 hidden buffer in use 

5 move required 

6 non-SCALARVARYING 

7 operation checked 

FFLF previous READ 

1 previous READ SET 

2 previous LOCATE 

3 previous REWRITE 

4 previous OPEN 

5 close in progress 

6 implicit close 

7 outstanding event or 
previous open 

I (VSAM resume load) 

FFLG Endpage 

1 end of extents 

2 COPY option active 

3 CONSEC UNBUFF 

4 unused 

5 Synad entered 

I 6 Newly opened print file 
7 File open 

FFLH In-line I/O 

1 In-line locate 

2 unused 

3 unused 

4 unused 

5 Blanks at end of record 

6 unused 

7 unused 

FLOP 7th character of OPEN module name 

I FFLI VSAM 

1-7 reserved 

FEFA offset of EOFADDR in DTF 

FERA offset of ERROPT address in DTF 

The common section is followed by either 
the RECORD or STREAM sections. 
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Record I/O Section 



FKLO KEYLOC-1 



Offsets are from start of the FCB. 



4C 
50 

54 
58 

5C 
60 
68 
70 

74 

78 

7C 
80 

84 



Current buffer address or 
Relative disk address (DAM) 



A (key area) 



Current record number (DAM) 
or A (embedded key) (ISAM) 



A (error module or bootstrap) 



A (event variable) 
or A (deblocker field in DTF) 



Stored record descriptor 



Stored key descriptor 



Stored request control block 

(first word) 
Address (associated files 
work area) 



0-format record length (DAM) 
A (LIOCS transmitter (SAM) ) 
Base OPTCD for RPL (VSAM) 



FKLO/FXXX | FECC | FEMT 
l/FFLVI 



Offset table for error check 



FEFT | FSAT | FNRT/ 

| | FFNC | FCNF 



FKLN/FLCFI FAFB | 
/FKYL | | 



unused 



FCDA|FRID 

FAKY 
FREL|FEKY 

FERK 
FEVT|FABL 

FARD 
FAKD 
FRCB|FAWB 

FURL|FALM| 
FOPT 

FRTB 



FXXX Error bytes for DAM 

FECC 2 for BACKWARDS (12 for FORWARDS) (Mag 
Tape only) 

IFFLV KSDS 1 ESDS 2-7 reserved 

FEMT 7th char of error module name 

FEFT 7th char of endfile module name 

FSAT saved attributes (consec unbuff) 

FNRT number of records/track (DAM) 

FFNC associated file byte 

FCNF Associated file conflicting operations 
flags 

FKLN Keylength-1 

FLCT Number of lines left on card 

FKYL Keylength (VSAM only) 

FAFB Associated file work byte 



Stream I/O Section 

Offsets are from the start of the FCB. 
2 





4C 


FRLM 


50 


FPGZ 


54 


FLNN 


58 




5C 




60 




64 



r 

I A (next 


availabl 


e byte in a buffer) 


I Eytes remaining 
I buffer 


in 


Value of count 
built-in function 


I Page size 


Line size 


I Current line no 


• 


Record size 


I A (copy 


position 


in bi 


iffer) 


I A (FCB for COPY 


file) 




I A (copy 

i 


module (i 
output 


nput)/ 
print 


'tab module 



4 

i 

I FCBA 

I 

I FCNT 

I 

I 

I FLNZ 

I 

I FMAX 

I 

IFCPF 

I 

IFCPF 

I 

IFCPAIFTAB 
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Flow Statement Table 



Function 

Used to implement the compiler FLOW 

option. Holds the last » n' statement 

number pairs and the last , m' procedure 

executed. ('n' and ' m 1 are programmer 

defined.) 

When Generated 

initialization if the FLOW option has been 
specified. The table is continually 
updated as the prgoram is executed. 



Where Held 



AFLG - Flags 

unused 

AFL1 - Flags 

ANON Bit No statement numbers required 

AFLI Bit 1 last entry was branch-in 

AILF Bit 2 unused 

AINT Bit 3 interrupt not recorded 

AGOT Bit 4 GOTO out of block 

Bits 5-7 unused 

AFLF - Flags 

ATBI Bit Branch-in entry 

ABCD Bit 1 BCD form for this entry 

Bits 2-7 unused 



Static internal control section. 



How Addressed 



From offset X • **C» in the TCA. 



ARGT 




4 

8 I 

C 

10 
14 

18 

1C 

20 
24 
28 














AFLL 


Total length of table 


ANEN 


A (next free 
sect.) 


field in stmt, no 


AASB 


A (start of names section of 
table) 


ANEB 


A (next free 
section) 


field in names 


AAEB 


A (end of table) 


ASBS 


A (start of numbers section) 




AFL1 I AFLF 


| AFLG ISTATE- 




MENT NO. (4 


bytes) | AFLF 




AFLG ( 


STATEMENT NUM- 




BEB | etc. 










ASBD 


NAMES 
I (8 


OF BLOCKS 
BYTES) 
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Input Output Control Block (IOCB) 



Func ti on 

To hold information about the current I/O 

operation on VSAM files. 

When Generated 

During the execution of the OPEN statement. 

Where Held 

In non-LIFO storage. 

3o,s_ Addressed 
From the FCB. 






r — ~ 
reserved 


4 


INXT 


8 


IFLA | IFLB | IEEE 


C 


IBCB 


10 


IOBD 


14 


IORL 


18 


IOKD 


1C 


IOKL 


20 


IEVT 


24 


IDUB 


28 


IKSV 


2C 


IEVC 


30 


IMHD 



34 
38 
3C 
40 



IMEL 



44 


ISHD 


48 


ISEL 


4C 


IHTC 


50 


IEPL 


54 


ISAE 


58 


ISLN 


1 


* 


5C 


1X34 


1 


♦ 


60 


IOPT 


64 


IX2C 


1 


* 


68 


IAEA 



6C 



70 



74 



78 



7C 



80 



84 



88 



8C 



90 



94 



* indicates reserved fields 



IX2D 


1 


* 


IAEL 


1X35 


1 


* 


IBCL 


1X38 


1 


* 


ISIK 


IX2E 


! 


* 


IAEG 


1X30 


1 


* 


IKYL 


* 



INXT 
IFLA 



IFLB 

IEER 

(IER1 
IEE2) 

IBCB 
IORD 

IOBL 

IOKD 

IOKL 

IEVT 
IDUB 
IKSV 
IEVC 

MODCB 

IMHD 
IMEL 

SHOWCB 

ISHD 
ISEL 



Next IOCB on chain (set to 0) 
Flag byte - bits set to » 1 • 
indicate: 



Bits 
Bit 4 
Bit 5 



- 3 



Bits 6-7 



reserved 

general error flag 

unable to complete 

operation 

reserved 

Code byte containing offset within 
•look-up 1 table used for record 
checking 

Error codes (as for FER1 S FEF2 
of FCB see under FCB) 
First byte is for TRANSMIT, 
second byte for ENDFILE, RECORD, 
KEY 8. ERROR conditions 
Reguest Control Block 
1st word of record descriptor = 
record address 

2nd word of record descriptor = 
flags ♦ record length 
1st word of key descriptor = key 
address 

2nd word of key descriptor = flags 
+ key length 
A (EVENT variable) 
A (dummy buffer) 
A (key save area) 
1st word of pseudo CCB 

plist (5 words starting at offset 

X'30«) 

A (header entry) -> IHTC 

Element entry addresses 

(maximum of 4) 

plist (2 words starting at offset 

X«44») 

A (header entry )-> IHTC 

A (element entry) 

deader control entry (4 words 
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starting at offset X»4C*) The 2nd word of each entry is used as 

IHTC header type code for MODCB/SHOWCB either a setting field for HODCB or a 

of FPL receiving field for SHOWCB. The IOCB field 

IEPL Address of reguest parameter list names are listed with their corresponding 

ISAR A (receiving area for SHOWCB) RPL (Request Parameter List) parameters. 
TSLN Length receiving area for SHOWCB 

Element control entries start at offset 
X'SC 1 and continue to end of IOCB. Each 
entry occupies 2 words, with keyword type 
code set in 1st half-word for example: 
1X34 = X«0034« 



IOPT 


OPTCD 


IARA 


AREA 


IARL 


AREALEN 


IRCL 


RECLEN 


ISIK 


FDBK 


IARG 


AR6 


IKYL 


KEYLEN 
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Interlanguage Root Control Block 
(IBMBILC1) 



How Addressed 



Function 



Connects ZCTL and interlanguage VDA to 
interlingual routines, and records state of 
activation of language interfaces. 



When Generated 



During compilation. 



Where Held 



In static internal storage, as a control 
section. 



By an offset from register 3 known to 
compiled code. 

1 2 3 H 

r : * ~ """* "t 

| Address of ZCTL | 

, , 

4 I COBOL | FORTRAN | Stack | | 
Iflag Iflag | flag I I 

L 1 

COBOL flag = COBOL active 

FORTRAN flag = FORTRAN active 

Stack flag = PLISA specified 

Note: If COBOL or FORTRAN flag is on PL/I 
is also active. 
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miinm i ii ii , iii . i iii"i» i n i M, iii ' i n i U) i i 



Interlanguage VDA 



Where Held 



Function 



In the LIFO storage stack. 



To hold information required for 
interlanguage calls. Used for information 
that alters from invocation to invocation. 



How Addressed 



The latest interlanguage VDA is addressed 
from offset in ZCTL. 



When Generated 



One interlanguage VDA is generated for each 
interlanguage call made from PL/I to 
FORTRAN or COBOL. An interlanguage VDA is 
also acquired if the PL/I environment has 
not yet been set up when PL/I is called 
from COBOL or FORTRAN. 



A (previous interlanguage VDA) 
or A (ZCTL for first VDA) 



Address of current DSA 



A (Callers error routine) 



Program | A (Callers machine check 
mask | save area) 
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Key Descriptor (KD) 



Word 1 



Function 



Contains address and length of key for 
passing to library record I/O routines. 



When Ge nerated 

As far as possible during compilation. If 
necessary, completed during execution. 



Where Held 



a. Address of source key (excluding 
the length bytes if VARYING) 



b. Address of where to put key 
(excluding length bytes if 
VARYING) 



Word 2 



Bit 



•1'B if KEYTO string is 
VARYING. (If this bit is set, 
the I/O transmitters will set 
the current length field) . 



Normally in static internal control 
section. In static external control 
section if key is EXTERNAL. Will be copied 
into, or generated in, temporary storage if 
procedure is reentrant or recursive. 



1 2 


3 




r ~ 
0| Address of KEY variable 


I Flags | 


Length 




I Region No. 







Bit 1 M'B if word 3 contains a 
region number. 



Bits 2-15 Unused (zero) 

Bits 16-31 Length of key string 

(excluding length bytes for 
VARYING) ; current length for 
KEY or KEYFROM, maximum length 
for KEYTO. 



Word 3 

Region number in fixed binary, right 
jjistified. 
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Label Data Control Block 



Function 



Ho w Addr essed 

As a variable, dependant on 
storage class. 



Holds the address of the data item and, if 
a label variable, the address of the 
associated DSA. 



When Ge nerated 



Label constants: 
Label variables: 
allocated 



during compilation 
when the variable is 



Label Var iable 



r " ~ ■*""" """"" "" "i 

| Address of label constant | 

, , 

I Address of DSA (at time of | 
U | assignment) of owning block | 

L -J 



Where Held 



Depends on the storage class of the data 
item 



Label Constant 

4 

r 1 

| Address of label | 
, , 

4 I Value to be loaded into | 

1 Register 2 on GOTO | 

L-— -— — ■ —————J 
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Library Work Space (LWS) 



Function 



Space reserved for two pre-formatted DSAs 
used by certain library modules. 



When Generated 



The first LWS is generated during program 
initialization. Subseguent LWSs are 
allocated before entry to any on-unit. 
This is because the on-unit may reguire the 
use of library modules using LWS but must 
not alter the environment of the interrupt. 



Hoy. Addressed The associated .allocations, is 
addressed from offset X'48* in the current 
DSA. 

2 4 




4 

50 
88 
8C 

D8 
110 



Flags (As DSA) | offset to ONCA 



Housekeeping information as for 
DSA 



56 bytes workspace 
Flags (as DSA) | offset to ONCA 



Housekeeping information as 
for standard DSA 



56 bytes workspace 
Current ONCA 



Where Held 



First allocation in the program management 
area. Subseguent allocations in the LIFO 
storage stack. ONCAs are generated with 
LWS. 
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On Communications Area (ONCA) 



= 1 ONCOUNT valid 



^unction 



An area in which built-in function values 
or their addresses are placed, after the 
occurrence of a PL/I interrupt. 



When Generated 



The first ONCA is generated during program 
initialization. Subsequent ONCAs are 
generated with each allocation of LWS. 



Where Held 



Contiguous with LWS in the program 
management area and in the LIFO stack, 



How. Add ressed By an offset held from the 
start of LWS held at offset X'02« in each 
segement of LWS. 



Dummy ONCA 



The dummy ONCA has the same format as other 
ONCAs and holds default values for those 
condition built-in functions that have 
default values. 

Flags 1 

Bit =0 ONFILE invalid 
= 1 ONFILE valid 

Bit 1 =0 ONCHAR/ONSOURCE invalid 
= 1 ONCHAR/ONSOORCE valid 

Bit 2 =0 ONIDENT invalid 
= 1 ONIDENT valid 

Bit 3 =0 ONKEY invalid 
= 1 ONKEY valid 

Bit 4 =0 DATAFIELD invalid 
= 1 DATAFIELD valid 

Bit 5 = No associated EVENT variable 
= 1 Associated EVENT variable 

Bit 6 Unused 

Bit 7 =0 ONCOUNT invalid 



Bits 8-15 unused 


4 
8 

10 

18 

20 

28 

30 

38 
3C 
40 
44 
48 
4C 
50 

Flags 2 
Bit 

Bit 1 



Chainback to previous 


ONCA 


ONCODE | 


f lagsl 


string locator 

ONFILE 


for 


string locator 
ONCHAR 


for 


string locator 
ONSOURCE 


for 


string locator 
ONKEY 


for 


string locator for 
DATAFIELD 


string locator 
ONIDENT 


for 


A (record I/O EVENT 


variable) 


Unused 


ONCOUNT 


retry environment 


retry offset 


X«40» | X»0000« | 


flags2 


LCT1 ILRAC | 


Unused 



LOCB 
LCDE 
LOFL 

LOCH 

LOSC 

LOKY 

LODF 

LOID 

LEVT 

LCNT 

LREN 
LRAD 



= ONSOURCE/ONCHAR not used in 

on-unit 

= 1 ONSOURCE/ONCHAR used 

= ONSOURCE not set in ONCA 
= 1 ONSOURCE set in ONCA 



Bits 2-7 unused 

LCT! 

Copy of TCA flag byte 1 (TFB1) 

Retry address code 

Re tr y off set 

The offset from the base of the library 
module involved to the address at which a 
conversion will be reattempted if ONSOURCE 
or ONCHAR has been used. 
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On Control Block (ONCB) 



Static ONCB 



Function 



Contains pointer to associated on unit, or 
indicates action to be taken when interrupt 
occurs. 



1 2 4 

r t 

Oj Code | Flags | Unused | 
, _ , 

4| Target | 

L . J 



When Generated 



Static ONCBs are generated during 
compilation, one for each ON statement. 
Dynamic ONCBs are generated by the prologue 
code of the procedure or block in which the 
ON statement occurs, or are allocated in a 
7DA when the ON statement is executed. 



Where Stored 



Static ONCBs are generated in the static 
internal control section. Dynamic ONCBs 
are stored in the DSA of the block in which 
the associated on-unit occurs. 



How Addressed 



Start of dynamic ONCBs - offset X^O 1 
in the DSA. 

First Static ONCB - offset X'5C« in DSA. 



Qualifier 



A(FCB) for I/O conditions 

A(SYMTAB) for CHECK 

A(CSECT) for CONDITION condition. 



Code 

PL/I code for condition 

Flags 

Bit 0=0 SYSTEM not specified 
1 SYSTEM specified 



Bit 1=0 Not a null on-unit 
1 Null on-unit 



Bit 2=0 Not a GOTO only on-unit 
1 GOTO only on-unit 



Bit 3=0 Condition not established 
1 Condition established 



Static a nd Dynamic ONCBs 



Bit 4 



Unused 



Static ONCBs are generated for ungualified 
conditions. Dynamic ONCBs are generated 
for gualified conditions (ENDPAGE, ENDFILE, 
etc.) 



Dynamic ONCB 

12 i* 

r — r 1 

0| Address of previous dynamic ONCB 

1 in block (or zero, if first) 



I 

4| 



Qualifier 



, 

8 | Code | Flags | Unused 
, 

C| Target 



Bit 5=0 Condition not enabled at block 
entry 
1 Enabled at block entry 



Bit 6=0 Condition disabled 
1 Condition enabled 



Bit 7=0 SNAP not specified 
1 SNAP specified 



Target 



Address of on-unit, or offset in DSA of 
word containing A (label variable or 
label temporary). 
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Open Control Block 



NPA - Open attributes 



Function 



Used to indicate that a file attribute 
(either input or output) was declared in 
the associated OPEN statement. 



When Generated 



During compilation. 



This word indicates the explicit and 
implied attributes on the OPEN statement. 

By te ., No . Hex. Value Attributes 



1 
2 

3,4 



Not used 

10 

20 
Not used 



INPUT 
OUTPUT 



NDEW -Op en , confl ic t ma s k 

This is a mask generated by the compiler 
containing bits for all attributes which 
conflict with those on the OPEN statement. 



Where Held 



Static internal control section. 



How Addressed 



By an offset from register 3 known to 
compiled code. 

r ' ' i 

0| NPA (word of attribute flags) | 

, .. _ _ _ , 

4| NDEP! | 

, , 

8| Unused I 

L . . . J 
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PLIMAIN 



Fg notion 

To hold address of entry point of a PL/I 
main procedure. 

W he n. ge ner a ted 

During compilation of a procedure with the 
MAIN option. 

W here held 

Separate control section. 



How Ad dressed 

As a control section. 

r i 

0| A (Entry Main Procedure) | 

, , 

4| Unused | 

L- — . 1 
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PLISTART How_Addressed 

As a control section, 

Function 

Entry point for PL/I program, passing 
control to IBMDPIR. Primary entry point 
passes control to IBMDPIR A.. PLICALLA 
passes control to IBMDPIRB. PLICALLB 
passes control to PLICALLC. 

When_Generated 

During compilation for every PL/I 
compilation. 

Where held 

Held as a separate control section. 



PLISTART 


CSECT 






EXTRN 


PLIMAIN 




BALP 


■15,0 




USING 


*,15 




L 


15 r PIR 




BALR 


0,15 




DC 


A PLIMAIN 


PIR 


EQO 


* 




DC 


V IBMBPIRA 




END 


PLISTART 
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Record Descriptor (RD) 



1. Address of the data to be written out. 



Function 



Contains address and length of record for 
passing to library record I/O routines. 



When Generated 



As far as possible during compilation. If 
necessary, completed during execution. 



2. Address of where data read in is to be 
put. 



3. LOCATE statement: Address of where to 

store buffer 
address. 



READ SET statement: Address of 

pointer to be 
set. 

READ IGNORE statement: Ignore factor. 



Where Held 



Normally in static internal control 
section. In static external control 
section if record is EXTERNAL. Will be 
copied into, or generated in, temporary 
storage if procedure is reentrant or 
recursive. 



How Addressed 



By an offset from register 3 known to 
compiled code. 

r t 

I A (record variable) | 

, , 

4 | length | 

L J 



J*ord_2 

Bits 0-7 indicate the type of INTO or 
FROM argument as follows: 

X *00' fixed length strings 

X •01' area variables 

X '02' varying length character 

strings 
X '03' varying length bit strings 

Bits 8-31 length of data to be transmitted 
(length of variable or buffer 
for locate mode) . 

The value is in bytes for all 
strings including bit strings. 

For VARYING strings, the value 
includes the two length bytes, 
and is the maximum length for 
input operations and for LOCATE, 
the current length for other 
operations. 
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Request Control Block (RCB) 



Function 



10 - DELETE 
14 - UNLOCK 
18 - WAIT 



Used by the record I/O interface module 
(IBMDRIO) to check the validity of an I/O 
statement. The instruction in RTMI is 
carried out by IBMDRIO. 



When Generated 



During compilation. 



where Held 



Static internal control section. 



How Addressed 



From parameter list passed in register 1 to 

IBMDRIO. 



1 2 3 
r 1 : " i 

| REQ1 | REQ2 | REQ3 | REQ4 | 
, .__ __. , 

4 | RTMI | 

L '■ 1 

1J0.1 (statement identification) 

00 - READ 
04 - REWRITE 
08 - WRITE 
0C - LOCATE 



RE Q2 (options) 

80 - INTO/FROM 
40 - SET 
20 - IGNORE 
02 - NOLOCK 
01 - EVENT 

REQ3 (options) 

01 - KEY 

02 - KEYTO 
04 - KEYFROM 

RE£4 unused 

Mil 

Either a TM or a BR instruction 
depending on source program. 

A TM instruction is used if the 
statement cannot be checked for validity 
during compilation, or if it has been 
checked and found to be invalid. 

The TM instruction is used by IBMDRIO 
for testing the validity of a statement and 
is; 

X»91MM2SSS« 

where MM is byte containing current 
statement bit and SSS is offset of 
corresponding byte in FCB statement mask. 

A BR instruction is used if the 
statement has been checked during 
compilation and found to be valid. 

Unconditional branch instruction to PL/I 
library or LIOCS transmitter. 
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Statement Frequency Count Table 



Function 

To retain a record of the number of times a 
statement has been branched to or from, for 
use by the COUNT option. 

When Generated 

When the associated external procedure is 
entered. 

Where .Held 

Non-LIFO storage. 

How Addressed 



The statement frequency count table for the 
first external procedure in a program is 
addressed from offset X^O' in the TCA 
appendage (TIA) . The tables are chained 
together and the chain field of the last 
table set to zero. The chain field is at 
offset in the table. The most recently 
used table is addressed from X*84* in the 
TIA. 





4 

8 
C 

10 

14 

18 

1C 

20 



A (next table 

A (static CSECT OF PROCEDURE) 

name of procedure 



flags 

A (first segment) 
A (next segment) 
number of entries 
length of segment 

count entry 
count entry 
count entry 



ACTB 
ACST 
A CEP 

ACFL 
ACBS 
ACSG 
ACNG 
ACLG 



| ACBS The address held in ACBS is the 

| address of ACSG. If tables are 

I segmented, second and subsequent 

| sections of the table will start at a 

| point equivalent to ACSG. 



IACFL 
i 


Flags 




IACBI 
1 


Bit 


last update was for a branch 
in 


|-ACGT 

i 
i 


Bit 1 


last update was for a GOTO 
out of block 


| ACIA 


Bit 2 


table inactive 


IACNM 


Bit 3 


not used 


IACUI 


Bit 4 


not used 


IACZC 


Bit 5 


not used 



Other bits unused. 
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Stream I/O Control Block (SIOCB) 



Function 



Holds addresses of source and target, 
source and target DEDs etc and is used as 
parameter list by stream I/O routines. 



When Generated 



During execution for the duration of the 
stream I/O statement. 



Where Held 



In temporary storage. 



How Addressed 



By register 1 during the stream I/O 
statement. 

2 



SSPC 
SSDD 4 
STRG 8 
STDD C 

10 
SFCB 14 
SRTN 18 
SAVE 1C 

SCNT 20 

SOCA 24 
SSTP. 28 



Address of source or its locator 

Address of source DED 
Address of target or its locator 

Address of target DED 
SFLG | STYP | SDSA | SDFL 

Address of FCB for file 

Address of next statement 



Save word used in compiler 
generated subroutines 



Value of COUNT | Unused 
built-in f unctn. j 



Address of ONCA 



Area used during GET or PUT string 
to hold dummy FCB. 



Flag Byte SFLG 

Bit 0=1 Transmit on input 

Bit 1=1 VDA used in edit-directed input 

Bit 2 = 1 IBMDSED is used 

Bit 3 = 1 Call to IBMBSIST reguired after 
dealing with next item (GET or 
PUT STRING only) 

SDSA 

DSA level number (used only for 
data-directed I/O) 

Type code STYP 

Bit 0=1 data-directed I/O 

Bit 1=1 list-directed I/O 

Bit 2=1 edit-directed I/O 

Bit 3=1 string I/O 

Bit 4=1 CHECK entry to data-directed I/O 

Bit 5=1 input 

Data-directed flag SDFL 

Bit 0=1 Terminating call to data-directed 
output 
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Statement Number Table (DST) 



Function 



To relate statement numbers to offsets so 
that statement numbers may be given in 
execution-time messages. 



therefore step down one section of the 
table. If the offset was XM8FFF 1 the 
binary would be '0001 1000 1111 1111 
1111'B. Ignoring the 15 right-hand bits 
leaves '11'B therefore step down three 
sections of the table.) 



When Generated 



During compilation, if the GOSTMT option is 
in effect. 



Where Held 



Static internal control section. 



How Addressed 



From offset 8 from each principal entry 
point to a block. 



Sections of Table 



As offsets are held in two bytes and the 
value may in fact take up to three bytes 
(4096) , it is necessary to hold the table 
in sections. If the offset is greater than 
X'7FFF' the statement number will be held 
in the second or subseguent sections of the 
table. Obtain the number given by 
translating the offset into binary and 
ignoring the last 15 bits and step down 
this number of sections of the table. (For 
example, if the offset was X'SFFF', 
translate to binary = ' 1000 1111 1111 
1111'B, ignore last 15 binary digits =1, 





2 




A primary entry point 


of block 


Size of 


code generated 
in bytes 


for block 


A (end of 


first section 


of table) 


Offset 


j Statement No. 


Offset 


| Statement No. 



further offsets and statement 
numbers 



A (end of second section of table) 



Offset 



| Statement No. 



Etc. 



* = End of first section 

Offset: Offset is the offset of the first 
byte of the statement relative to 
the address of the primary entry 
point of the block. 
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String Locator/descriptor 

Function 



Used to pass the address and the length of 
strings to other routines. Also for 
handling strings with adjustable lengths 
(e.g., DCL STRING CHAR (N) ) . 



When Generated 



Storage reserved during compilation. 
Fields completed during execution if string 
has adjustable length. 



Word 2 
Bit 16 

F = , 0» B Fixed string (First bit of second 
byte) 
•1* B Varying string 

Bits 29-31 

F2 Used for bit strings to hold offset from 

byte address of first bit in string (3 
bits) 

Allocated length 

For varying strings this is the declared 
length. Length is held in bits for bit 
strings and in bytes for character strings. 



Where Held 

Static internal control section. 

How, Ad dressed 

By an offset from register 3 known to 
compiled code. 



1 2 3 4 

r r ~ .-: • -— ' — -i 

0| Byte address of string | 
, _. ... ._ , 

4 | Allocated length |F| unused |F2| 

Bit 16 Bits 29-31 



STRING DESCRIPTOR 



The string descriptor is the second word of 
the string locator/descriptor. It appears 
in structure descriptors and in the 
description field of controlled variables. 
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Structure Descriptor 



Function 



Contains information about the offset of 
each element within a structure, and the 
nature of each element. Used when passing 
a structure to another routine, or for 
accessing structure elements during 
execution, if the structure is declared 
with adjustable extents or with the REFER 
option. 



fullword field containing the offset of the 
start of the element from the start of the 
structure is given. If the base element is 
a string, area, or array, this fullword is 
followed by the offset field for the next 
base element. 



When Generated 



If the structure has no adjustable 
elements, during compilation. If the 
structure has adjustable elements, during 
execution from information held in the 
aggregate descriptor descriptor. 



Where Stored 



Static internal control section. 



How Addressed 



Offset of element from start 
of structure 



Descriptor of element if 
element requires descriptor 



Offset of element from start 
of structure 



Descriptor of element if 
element requires descriptor 



etc 

For every base element in 
the structure, an entry is 
made consisting of an 
offset field and, if the 
element requires a descrip- 
tor, a descriptor. 



By an offset from register 3 known to 
compiled code. 



Offset 



General Format 



For each base element in the structure, a 



The offset field is held in bytes. Any 
adjustments needed for bit-aligned 
addresses are held in the respective 
descriptors. 
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Symbol Table (SYMTAB) 



Function 



Bit 4 = M'B item may appear in some 
CHECK list. 
= 'O'B item appears in 
no CHECK list. 



Holds the name of the variable during 
execution and associates it with the 
address of the variable. Used only when 
data-directed I/O or the CHECK condition is 
specified. 



(Bit 4 must be M'B if item is EXTERNAL) 



Bit 5 = M'B Address field A refers to 
data. 
= »0'B Address field A refers to 
locator. 



When Generated 



During compilation, if data-directed I/O or 
the CHECK condition is used in the program 



(Bit 5 must be 'O'B for a CONTROLLED 
parameter) 



Bit 6 = M'B a member of a structure. 

= 'O'B not a member of a structure. 



Where Held 



Static internal control section for 
internal names. Separate control section 
for external names. For external variables 
the name of the control section is the name 
of the variable followed by an *. 

Ho J8_ Addressed 

By an offset from register 3 known to 
compiled code for internal variables. As a 
control section for internal variables. 



10 



Flags | Dimension 
I ality 


Level 
number 


A(DED) 


Address field A 




Address field B 


Length of name \ 




Name (fully gualified) 





Bit 7 = M'B Normal SYMTAB. 

= 'O'B Short SYMTAB (has fields A & 
B omitted) . 

Bit 8 - M'B Address field A addresses 
code. 
= »0'B Address field A does not 
address code. 

Bits 10 - 11 reserved: must be set to 
•O'B. 

Bit 12 = M'B Symtab concerns a BASED 

variable; Bits 0,1 , 2, 5, 8 of 
Flags, level # and Field A 
all refer to the POINTER 
gualifier. 
= »0'B normal Symtab. 

Bit 13 = M'B Symtab concerns a BASED 

variable and Field B contains 
an address (in Static). 
= »0'B If Symtab concerns a BASED 

variable, Field B contains an 
offset (right justified) in 
the DSA defined by level #. 



Bits 14,15 



reserved: 
'O'B. 



must be set to 



flags 

Bits 0,1 6 2 = 



•000'B STATIC 

•100'B AUTOMATIC 

'010' B CONTROLLED 

(not param.) 

•001'B BASED 

•011' B DEFINED 

•101 'B a non-CONTROLLED 

parameter 

M11«B a CONTROLLED 

parameter 



Bit 3 = M'B EXTERNAL 
= »0'B INTERNAL 



Dimen sionalit y 

The number of dimensions declared for 
an array item. Dimensionality is zero for 
other items. 

Level number 

(for AUTOMATIC, DEFINED, and BASED items. 
Also for all parameters.) The level of the 
block in which the variable is declared. 
The level of a block is one greater than 
the level of the immediately containing 
block; the level of the external block is 
0. 



254 



Address Fields 



Addresses are held in different formats for 
different data types. As far as possible, 
addresses are held in address field A. 
However, more information than can be held 
in a fullword field is sometimes required. 
When this is the case, address field B is 
also used. 



Address field A 

If STATIC Address of data or address of 
locator for items that have 
locators. 

If AUTOMATIC Offset within the associated 
DSA of the data or of the 
locator for items that have 
locators 

If CONTROLLED Address of anchor word. 



If structured not BASED 

Offset from start of structure 
descriptor to field that holds 
offset of element from start 
of structure. See "Structure 
Descriptor. " 

If BASED (except when flag bit 12 or 13 is 

set) 

For non-structured BASED items 
field B holds the offset of 
the descriptor from the start 
of the DSA in which it is 
held. 

For structured BASED items, 
the offset is to the offset 
word in the structure 
descriptor. This word holds 
the offset of the item from 
the start of the structure. 
See "Structure Descriptor". 

Length 



If BASED Offset of one word field with 
in associated DSA containing 
address of declared pointer 
qualifier. 

If PARAMETER or DEFINED 

Offset of one word field in 
associated DSA containing 
address of corresponding 
argument, or DEFINED data, or 
its locator. For CONTROLLED 
parameters, the argument is 
its anchor word. 



Length is the number of characters in the 
fully qualified name. 



Address field B 

If non-structured AUTOMATIC, STATIC, 
DEFINED or CONTROLLED 
parameter, field B is set to 
a fullword of zeros. 



Appendix B: Control Blocks 255 



Symbol Table Vector 



Where Held 



Function 



Holds addresses of symbol tables and 
associates them with the block in which the 
associated names were declared. 



Static internal control section. 

How Addressed 

Ey an offset from register three known to 
compiled code. 



When Generated 



Durinq compilation. 




A (symbol 


table) 






A (symbol 


table) 






• 


fullword 


of zeros 






A (of first entry in symbol 
of encompassing block) , All 
for main procedure block 


table 
zeros 


vector 


etc. 



< — marks end of 
block. 



General_Format 

The format of symbol table vector is a 
series of fullwords. These contain either: 

1. The address of a symbol table 
or 

2. The address in the symbol table vector 
of the start of the entries for the 
encompassing block. 

or 

3. A fullword of zeros indicating the end 
of the current block. 
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Task Communications Area (TCA) 



when Generated 



Function 



During program initialization by IBMDPIR. 



Acts as a central communications area for 
the program. Contains addresses of 
essential routines and control blocks, and 
various flags. (See chapter 5) . 



Ho w_J\ d dressed By register 12 -43 





r t 
Flags | 


4 j 


Unused j 


8 


Segment #| BOS j 


c 


Segment #| BOS | 


10 


Unused j 


14 


A (current event variable) | 


18 


A (External Save Area) I 


1C 


A(TRT Table) | 


20 


A (overflow routine - get DSA) | 


24 


Branch to get DSA subroutine | 


28 


A (TCA appendage) j 


2C 


A (error handler) | 


30 


A (Save Area for Overflow Routine) | 


34 


Open File Chain Anchor | 


38 


Branch instruction for TCA GOTO codej 


3C 


A(Bugtable) j 


40 


A (Diagnostic File Block) | 


TURC 
44 


PL/I Return Code | User return | 
I | Code j 


48 


A (Overflow Routine for Get VDA) | 


4C 


A (Flow stmt number table) | 


50 


A (Tab table) | 


54 


A (Flow module) | 


58 
5C 


Branch instruction for call routine! 

Branch instruction for link routine! 

Unused j 


60 


Unused | TRLR ! TTLR | 


64 


(Set to zero) | 



Where Held 



In the program management area at the head 
of the initial storage area (ISA) . 

TFLG 



TBOS 
TEOS 

TEVT 
TESA 
TTRT 
TOVF 
TGDS 
TTIA 
TERR 
TPSA 
TFOP 
TGTC 
TBUG 
TDFB 
TORC 

TOW 

TFST 

TTAB 

TEFL 

TCAL 
TLIN 

TENV 
TPRI 
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68 
6C 
70 
74 
78 
7C 
80 

FO 

F4 

F8 

FC 

100 

104 

108 

10C 

110 
114 
118 



Onused 

A (Get Dynamic Storage Routine) 
A (Free Dynamic Storage Routine) 
A (Overflow Routine for Get DSA) 

A (Error Handler) 
Environment Description 



Normal GOTO Code 
Used when GOTO out of block may 
occur 



A(IBMBEFLC)/ 
dummy if NOFLOW 


and 


NOCOUNT 


A (Interpretive 


GOTO 


routine) 


Unused 


Unused 


Unused 



Unused 

A (WAIT routine) 



A (COMPLETION pseudovariable 
routine) 



A (EVENT assign routine) 

Unused 
2 unused words 



TGET 

TFRE 

TOVFO 

TERRO 

TENVO 

TGTCO 

TEFC 
TGTM 



TAWT 
TACP 

TAEA 



TFLG contains flag bytes TFB0, TFB1, TFB2, and TFB3. 

Bit 

TFB0 all not used in this 

implementation 
TFB1 not used 

1=»1'B Event I/O on-unit active 

2 not used 

3= , 1 , B Abnormal exit reguiring 

special action 
4-7 not used 
TFB2 0='1'B Raise SIZE for fixed- 
point divide, fixed-point 
overflow, exponent overflow, 
decimal overflow exceptions 
1=f|iB Ignore the exceptions 

detailed for bit 
2-6 not used 
7=M'B I/O conversion 
TFB3 all not used 

TENV contains environment description 
TRLR resident library release number 
TTLR transient library release number 

TOVFO TERRO TENVO TGTCO 

These fields are used in previous releases 
and are retained for compatibility. 
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TCA Appendage (TIA) 



Functi on 

To hold control and communication information. 

When G enerated 

During program initialization. 

Where Held 

Program management area. 

How., Addressed 

Prom Offset X f 28« in the TCA 



10 
14 
18 
1C 

24 
6C 
70 

74 
78 
7C 

I 80 

I 

|84 

I 

I 88 

I 



90 



A (Byte beyond ISA) 



Unused 



A (Last Free Area) 



Flags | Unused 



A (Dummy DSA) 



A (Get LWS code) 



A (Load Module Chain Anchor) 



Two words for code to call 
IBMBERRA 



Interrupt Save Area (18 words) 



A (Interrupt Handler 



A (latest DSA) for abnormal 
termination 



Word for A(IBMBCCLA) 



(communications region) 



A (Operation exception checking 
code) 



A (first count table) 



A (last count table used) 



Saved address of TCA to be 
restored after interrupt 



98 «-- 



Space for system tab table 
(IBMBSTAB) 



TISA 

TLFE 
TFL1 
TDDS 
TLWR 
TLMC 
TEBL 

TSAI 
TEBA 
TABT 

TCCL 
TCOB 

TAFF 
TCTF 
TCTL 

TATC 
TTBS 
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Flags - TFL1 

TFLS Bit 1=0 SYSPRINT not open for STREAM 
PRINT 
= 1 SYSPRINT open STREAM PRINT 

TFLJ Bit 2 = Abnormal termination exit 
not in progress 
= 1 Abnormal termination exit in 
progress 

TFLK Bit 3 = No dump I/O in progress 
= 1 Dump I/O in progress 



Notes on various fields 

TISA identifies end of region. 

Note; Chain beginning in TLFE is continued 
at offset 4 in free area. First word in 



free area contains length. 



TLWR is an address in IBMDPIR that acquires 
library workspace. 

TEP.A is entry point A of IBMDERR. 

TCCL is a field used to hold the address of 
the complex string conversion routine 
IBMBCCL. This routine is in the 
transient library and is loaded by the 
bootstrap routine IBMBCCS. When the 
routine is loaded, the address is 
placed in the field TCCL. 

TAFF is the address of the code used to 

check whether an operation interrupt 
is caused by an attempt to execute a 
floating point instruction on a 
machine with no floating point 
hardware. 
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Zygo-Lingual Control List (ZCTL) 



Function 



To hold information required for 
interlanguage calls. Holds information 
that does not change for every invocation. 



When Generated 



On the first interlanguage call. 



Where Held 

In the LIFO stack if PL/I is main 
procedure. If COBOL or FORTRAN are 
principal procedures, at the head of the 
unused portion of the region immediately 
before the TCA. 

How Addresses 

From offset X«0« in IBMBILC1 the 



Interlangauge Root Control Block. 

H 

i : — m t 

A (latest interlanguage VDA) . If none, 



4 
8 

c 

10 

18 
60 

80 



A (COBOL error routine) , if any 



A (Save area for COBOL program mask, 
if any) 



A (FORTRAN error routine) 



A (Save area for FORTRAN program mask) 



Address TCA 



Save Area 1 (18 words) 
Save area used by IBMBIEPA 



Short Save Area (8 words) 
Used as DSA when principal procedure 
is not in PL/I 



Save Area 2 (18 words) 
Used as DSA when principal procedure 
is not in PL/I 
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Appendix C: List of PL/I Library Modules 



The following list of modules is arranged in alphabetical order of 
the last three letters of the module name. This ordering is used to 
save the reader the trouble cf remembering whether the module is 
prefixed with IBMB or IBMD. 



Resident Library Modules 



Name 



IBHBAAK 

IBBEAIH 

IBMBAMM 

IBMBANM 

IBHE'APC 

IBMEAPF 

IBMBAPM 

IBHEASC 

IBMBAS? 

IBMBAYF 

IBMEEBA 

IBMBBBN 

IBMEBCI 

IBMEBCK 

IEMEECT 

IBMBBCV 

I3MBBGB 

IBMEBGC 

IBMBBGF 

IBMEBGI 

IBMBBGK 

IBMBBG3 

IBMEBGV 

IBMECAC 

IBMECEB 

IBMECBC 

IBHBCBQ 

IBMECCA 

IBMECCB 

IBMECCC 

IBMBCCQ 

IBMDCCS 

IBHECE 

IBMBCGP 

IBMBCGQ 

IB.HBC6T 

IBMBCG7. 

IBHBCH 

IBMBCK 

I3MBCM 

IBMBCO 

IBMBCP 

IBMBCR 

IBMBCT 

IBMBCU 

IBMBCV 

IBMBCW 

IBHBCY 

IEMDEFL 

IBMBEOC 

IBHBEOL 

IBMEERC 



Function 



ALL, ANY (simple and interleaved arrays) 

Indexer for interleaved arrays 

Structure mapping 

STBING built-in function 

PROD (arrays with fixed point integer elements) 

P50E (arrays with floating point elements) 

STRING pseudovariable 

SUM (arrays with fixed-point elements) 

SUM (arrays with floating-point elements) 

POLY built-in function 

AND, OR operations (byte-aligned bit strings) 

NOT operation (byte-aligned bit strings) 

INDEX (character strings) 

Concatenate, REPEAT (character strings) 

TRANSLATE (character strings) 

VERIFY (character strings) 

BCOL (bit strings) 

Compare (general bit strings) 

Assign (byte-aligned bit strings) and Fill (general bit strings) 

INDEX (bit strings) 

Concatenate, REPEAT, General Assign (bit strings) 

SUBSTR SLD 

VERIFY (bit strings) 

Conversion director (arithmetic to character) 

Conversion (bit to bit) 

Conversion (bit to character) 

Conversion (bit to pictured character) 

Conversion director (character to arithmetic) 

Conversion (character to bit) 

HIGH, LOW, Assign (character strings) 

Conversion (character to pictured character) 

String conversion director bootstrap 

Conversion (fixed decimal - free decimal - float - fixed binary) 

Check input (pictured decimal) 

Check input (pictured character) 

Table of powers of ten 

Set a subfield of a complex number to zero 

Conversion 

Conversion 

Conversion 

Conversion 

Conversion 

Conversion 

Conversion 

Conversion 

Conversion 

Conversion 

Conversion 



(fixed binary - float - free decimal) 

(fixed decimal - free decimal - fixed decimal) 

(pictured decimal to packed decimal) 

(packed decimal to pictured decimal) 

(bit to fixed binary or float) 

(fixed binary or float to bit) 

(decimal constant to packed decimal) 

(binary constant to float) 

(packed decimal to E format) 

(packed decimal to F format) 

(fixed binary to fixed binary and float to float) 



FLOW and COUNT option 

ON-code 

ONLOC built-in function 

CF.ECK system action 



Size 




(approx] 




390 


bytes 


100 


bytes 


1760 


bytes 


1630 


bytes 


580 


bytes 


370 


bytes 


1230 


bytes 


420 


bytes 


330 


bytes 


380 


bytes 


520 


bytes 


400 


bytes 


200 


bytes 


610 


bytes 


770 


bytes 


210 


bytes 


660 


bytes 


240 


bytes 


390 


bytes 


350 


bytes 


890 


bytes 


330 


b y te s 


420 


bytes 


700 


bytes 


350 


bytes 


220 


bytes 


240 


bytes 


520 


bytes 


420 


bytes 


270 


bytes 


410 


bytes 


340 


bytes 


720 


bytes 


870 


bytes 


200 


bytes 


140 


bytes 


300 


bytes 


480 


bytes 


370 


bytes 


810 


bytes 


1080 


bytes 


490 


bytes 


400 


bytes 


670 


bytes 


780 


bytes 


670 


bytes 


490 


bytes 


250 


bytes 


1200 


bytes 


220 


bytes 


160 


bytes 


490 


bytes 
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IBMEERR Error handler 

IBMPEVO Event Variable operations 

IEMDIEC Interlanguage housekeeping 

IBMDIEF Interlanguage housekeeping 

IBMDIEP Interlanguage housekeeping 

IBMDJDS DISPLAY 

IBMDJDT LATE built-in function 

IBMDJDY DELAY 

IBMBJD 7 DISPLAY without EVENT 

IBMDJTT TIME built-in function 

IBHEJWi WAIT (array events) 

IBMDJWT WAIT (multiple events) 

IBMGJWT WAIT (single event) 

IBMDKCP Checkpoint/restart interface 

IBMDKDM Dump bootstrap 

IEMDKS? SORT interface 

IBMEMAL SQET (long float real) 

IBMEMAS SQRT (short float real) 

IBMEMAX SQRT (short float complex) 

IBMBMAY SQRT (long float complex) 

IBMEMBL EXP (long float real) 

IBMBMBS EXP (short float real) 

IEMEMBX EXP (short float complex) 

IBMBMEY EXP (long float complex) 

IBMEMCL ERF, ERFC (long float real) 

IEMBMCS ERF, ERFC (short float real) 

IBMBMDL LOG, L0G2, LOG10 (long float real) 

IBMBMDS LOG, LOG2, LOG10 (short float real) 

IBMBMDX LOG (short float complex) 

IBMEMDY LOG (long float complex) 

IBHBMGL SIN, SIND, COS, COSD (long float real) 

IBMEKGS SIN, SIND, COS, COSD (short float real) 

IEMEMGX SIN, SINH, COS, COSH (short float complex) 

IBMBMGY SIN, SINH, COS, COSH (long float complex) 

IBMEMHL TA.N, TAND (long float real) 

IBMEMPS TAN, TAND (short float real) 

IBMBMHX TAN, IANH (short float complex) 

IBMEMHY TAN, TANH (long float complex) 

I3MBMIL SINH, COSH (long float real) 

IBMEMis SINH, COSH (short float real) 

I3MBMJL TANH (long float real) 

IBMEMJS TANH (short float real) 

IBMBMKL ATAN, ATAND (long float real) 

I3MBMKS ATAN, ATAND (short float real) 

IBMBMKX ATAN, ATANH (short float complex) 

IBMBMKY ATAN, ATANH (lonq float complex)' 

IBMEMLL ATANH (long float real) 

I3MB. M LS ATANH (short float real) 

IBMEMML ASIN, ACOS (long float real) 

IBM3MMS ASIN, ACOS (short float real) 

IBMBMOD ADD (fixed decimal real or complex) 

IBMBMP7 MULTIPLY (fixed binary complex) 

TBHBMPV MULTIPLY (fixed decimal complex) 

IBM3MQU DIVIDF. (fixed binary complex) 

IEMBMQV DIVIDE (fixed decimal complex) 

IBMBMPU ABS (fixed binary complex) 

IBMEMRV ABS (fixed decimal complex) 

IBMBMPX ABS (short float complex) 

IBMBMRY ABS (long float complex) 

IBMBMIID Shift and assign/load (fixed decimal real) 

IBMBMVU Multiplication and Division (fixed binary complex) 

IBMEMVV Multiplication and Division (fixed decimal complex) 

IBMBMVW Multiplication . (long and short float complex) 

IBMEMWX Division (short float complex) 

IBMBMWY Division (long float complex) 

IBMEMXL Integer exponentiation (long float real) 

IBMBMXS Integer exponentiation (short float real) 

IBMBMXW Integer exponentiation (short and long float complex) 



1500 

16 

500 

910 

1000 
740 
80 
130 
590 
150 
390 
800 
220 
820 
140 

1440 
170 
170 
290 
300 
460 
2b0 
140 
140 
640 
410 
340 
260 
230 
230 
390 
310 
310 
370 
320 
260 
230 
230 
240 
160 
260 
200 
470 
360 
260 
260 
260 
180 
350 
260 
290 
290 
280 
460 
580 
210 
540 
120 
130 
360 
290 
660 
120 
100 
100 
140 
140 
410 



bytes 
bytes 
bytes 
bytes 
bytes 
bytes 
bytes 
bytes 
fcytes 
bytes 
bytes 
fcytes 
bytes 
bytes 
bytes 
fcytes 
bytes 
bytes 
bytes 
bytes 
fcytes 
bytes 
fcytes 
fcytes 
bytes 
fcytes 
bytes 
fcytes 
bytes 
bytes 
bytes 
bytes 
fcytes 
bytes 
bytes 
fcytes 
bytes 
bytes 
bytes 
bytes 
fcytes 
bytes 
bytes 
bytes 
fcytes 
bytes 
fcytes 
bytes 
bytes 
fcytes 
bytes 
fcytes 
bytes 
bytes 
bytes 
fcytes 
bytes 
cytes 
bytes 
by t es 
bytes 
bytes 
bytes 
fcytes 
bytes 
bytes 
fcytes 
bytes 
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IBMBMYL General exponentiation (long float real) 

IEHBMYS General exponentiation (short float real) 

IBMBMYX General exponentiation (short float complex) 

IBMBMYY General exponentiation (long float complex) 

IBHDOCL OPEN/CLOSE* bootstrap 

IBMEOCN OPEN/CLOSE address list and record I/O error bootstrap 

IBMEPAE Controlled variable management 

IBMBPAM AREA management 

IBMEPGO Beset CHECK enablement 

IBMDPGR Storage management 

IBMDPIR Program initialization from system 

IBMDPJR Program initialization from caller 

IBMDPOV Overlay 

IBMBPPC Return cede module. 

IBMDPIO Record I/O interface module 

IBMBSAI Input conversion director (A, P, and B formats) 

IBMBSAO Output conversion director (A format) 

IBMESBO Output conversion director {character-P and B formats) 

IBMBSCI Input conversion director (C format) 

IBMBSCO Output conversion director (C format) 

IBMDSCP COPY 

IBMDSCV Conversion fix-up bootstrap 

IBMDSDI Data-directed input 

IBMESDJ Data-directed input 

IBMDSDO Data-directed output 

IBMESED Edit-directed I/O housekeeping 

IBMDSEE Edit— directed combination module 

IBMDSEH Edit-directed combination subset module 

IBMDSEI Edit-directed input 

IBMDSEO Edit-directed output 

IBMBSFI Input conversion director (F and E formats) 

IBMBSFO Output conversion director (F and E formats) 

IBHDSII GET FILE initialization 

IBMDSIO PUT FILE initialization 

IBMDSIS GET or PDT STRING initialization 

IEMDSLI List-directed input 

IBMDSLJ List-directed input 

IBHDSLO List-directed output 

I3MESMW Missing output width module 

IBMESPI Input conversion director (P format) 

IBMDSPL PAGE, LINF, and SKIP 

IBMBSPO Output conversion director (P format) 

IBMDSTF Stream input transmitter 

IBMDSTI Stream print F-format transmitter 

IBMDSXC X and COLUMN format items 

IBMBTOC COMPLETION pseudovariable and Event variable assignment 



160 


bytes 


150 


bytes 


260 


bytes 


270 


bytes 


240 


bytes 


200 


bytes 


150 


bytes 


540 


bytes 


40 


fcytes 


610 


bytes 


420 


bytes 


330 


bytes 


110 


bytes 


40 


bytes 


-so 


bytes 


420 


bytes 


130 


bytes 


400 


bytes 


300 


bytes 


290 


bytes 


230 


bytes 


90 


bytes 


2090 


bytes 


2090 


bytes 


1210 


bytes 


1050 


bytes 


1420 


bytes 


880 


bytes 


440 


bytes 


210 


bytes 


240 


bytes 


210 


bytes 


420 


bytes 


330 


bytes 


350 


bytes 


2220 


bytes 


2070 


bytes 


1610 


bytes 


340 


bytes 


370 


bytes 


530 


bytes 


290 


bytes 


440 


bytes 


190 


bytes 


440 


bytes 


130 


bytes 



Transient Library Modules 



The following list is arranged in alphabetical order of the last 
three letters of the module name. This ordering is used to save the 
reader the trouble of remembering whether the module is prefixed 
with IBMB or IBMD. 



Name 



Function 



Size 
(approx) 



IBMECCL Conversion director (complex strings) 

IBMBCCR Conversion director (ncn_complex strings) 

IBMBEOC On-code translate 

IBMBETA Miscellaneous non-ON messages (1) 

IBMBETB Miscellaneous non-ON messages (2) 

IBMBETC Misc. and computational non-ON messages 



1830 bytes 

940 bytes 

240 bytes 

710 bytes 

1140 bytes 

1000 bytes 
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IBMEETI I/O. non-ON messages 

IBMBETO ON messages (1) 

IBMBE7P ON messages (2) 

IBMBETQ ON messages (.3) 

IBMEETT EVENT messages 

IBMDEDO Open diagnostic file 

IBMDEDW Console transmitter 

IEMEESM Error message module phase 1 

IBMDESN Error message module pahse 2 

IBMDESY Error system action 

IBMDKDD Hexadecimal dump 

IBMDK7A Dump file attributes 

IBMEKDR Dump storage report 

IBMDKDT Dump/CODNT transmitter 

IEMDKMR Dump control 

IBMDKPT Dump parameter translate 

IBMDKTB Save Area Control Block printout 

IBMDKTC Save Area chain validity checker 

IBMBKTE Dump trace 

IBMDOCA Close 

IENEOCV Close VSAM files 

IBMDOPM OPEN - consecutive unbuffered files 

IBMDOP? OPEN - consecutive buffered files 

IEMDOPQ OPEN - consecutive buffered files (level 2) 

IBMDCPS OPEN - stream files 

IBMDOPT OPEN - stream files (level 2) 

IBMDOPU OPEN - consecutive buffered/stream files (level 3) 

IBMDOPV Open VSAM files 

IBMDOPW OPEN - indexed files (level 4) 

IBMDOPX OPEN - regional and indexed files 

IBMDOPY OPEN - regional/indexed files (level 2) 

IBMDOPZ OPEN - regional indexed files (level 3) 

IPMDPE? Housekeeping Diagnostic message module 

IBMDPES Storage management Diagnostic message module 

IBMDPIF Operation Exception checking, (no floating-point hardware) 

IBMDPII Program ISA initialization 

IEMEPJI Program ISA initialization from caller 

IBMDRAW Regional(3) sequential unbuffered output transmitter 

IBMDEA7 Regional (3) sequential buffered output transmitter 

IBMDEAY Regional (1) sequential unbuffered output transmitter 

IBMDRAZ Regional (1) sequential buffered output transmitter 

IEMERB9 Regional (1) sequential buffered input/update transmitter 

IBMDfcBX Regional (3) sequential buffered input/update transmitter 

IBMPRBY Regional (3) sequential unbuffered input/update transmitter 

IBMDRBZ Regional (1) sequential unbuffered input/update transmitter 

IBMDRry Consecutive sequential unbuffered transmitter, U-format 

IEMERCZ Consecutive sequential unbuffered transmitter, F-format 

IBHDPDY Regional (3) direct transmitter 

IBMDRDZ Regional (1) direct transmitter 

I3MDREF ENDFILE module 

IBMDPEX Error handler for indexed files 

IBMDREV Error handler for VSAM files 

IBMDREY Error handler for regional and unbuffered consecutive files 

IBMD5EZ Error handler for buffered consecutive files 

IBMDFJZ Indexed sequential input/update transmitter 

IBMDEKZ Indexed direct input/update transmitter 

IBMDRLZ Indexed sequential output, transmitter 

IBMDPRR Consecutive buffered exit module 

IBMPRFT Consecutive sequential buffered OMR transmitter, F-format 

IBMDRSU Consecutive sequential buffered associate files, U-format 

IBMDERV Consecutive sequential buffered associate files, V-f ormat 

IBMDRRW Consecutive sequential buffered associate files, F-fcrmat 

IBMPEVE VSAM KS DS direct transmitter 

IBMDPVS VSAM KSDS sequential input/update transmitter 

IBMDRVT VSAM KSDS sequential output transmitter 

IBMDRVZ VSAM ESDS transmitter 

IBMDBRX Consecutive sequential buffered transmitter, U-format 

IBMDREY Consecutive sequential buffered transmitter, V-format 



1340 


bytes 


1380 


bytes 


760 


bytes 


1020 


bytes 


1140 


bytes 


210 


bytes 


190 


bytes 


1010 


bytes 


2250 


bytes 


180 


bytes 


1000 


bytes 


3300 


bytes 


1100 


bytes 


1550 


bytes 


1040 


bytes 


380 


bytes 


2100 


bytes 


360 


bytes 


3600 


bytes 


1740 


bytes 


460 


bytes 


1250 


bytes 


1000 


bytes 


870 


bytes 


1030 


bytes 


1080 


bytes 


780 


bytes 


2260 


bytes 


740 


bytes 


1130 


bytes 


760 


bytes 


550 


bytes 


780 


bytes 


1580 


bytes 


130 


bytes 


910 


bytes 


760 


bytes 


710 


bytes 


650 


bytes 


770 


bytes 


680 


bytes 


860 


bytes 


860 


bytes 


1040 


bytes 


1020 


bytes 


1020 


bytes 


1030 


bytes 


950 


bytes 


850 


bytes 


170 


bytes 


580 


bytes 


730 


bytes. 


690 


bytes 


490 


bytes 


1410 


bytes 


960 


bytes 


660 


bytes 


300 


bytes 


400 


bytes 


360 


bytes 


380 


bytes 


620 


bytes 


1380 


bytes 


1820 


bytes 


970 


bytes 


1460 


bytes 


520 


bytes 


620 


bytes 



266 



IBMDREZ Consecutive sequential buffered transmitter, F-format 620 bytes 

IEMESCT Conversion condition interface 470 bytes 

1BMDSOF Stream output transmitter, ?-format 210 bytes 

IBMDSOU Stream output transmitter, U-format 170 bytes 

IBMESOV Stream output transmitter, V-fcrmat 210 bytes 

IBMBSTA Tab table 40 bytes 

IBMDSTU Stream print transmitter, 0-format 410 bytes 

IBMDSTV Stream print transmitter, V-format 430 bytes 
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Index 



abnormal GOTO 

code in TCA 59 

event I/O 156 

interpretive GOTO subroutine 28 

routine IBMBPGO 58 

SOFT exit 150 
abnormal locate return address 96 
access method 

record I/O 95 

stream I/O 118 
activating blocks 23 
actual origin (AO) 43 
address constants 9 
addresses 

DSA 17 

external save area 58 

library subroutines 16 

parameter lists 17 

program base 17 

static base 17 

TCA 17 

temporary base 17 

within TCA 5 8,59 
addressing 

beyond 4K limit 21 

controlled variables 19 

interrupt 71 

library subroutines 17 

register usage 17,18 

through locators 43-45 
adjustable extents 

control blocks 43 

creation of temporaries 19 
aggregates 

address 21,45 

array I/O 131 

arrays of structures 22,49 

assignments 23 

COBOL 189i 203 

descriptor descriptor 43-50,216 

FORTRAN 189,203 

interlanguage arguments 189,203 

library subroutines 14 5 

listing 11 

locator 45,217 

main discussion 22 
alignment in structures 189 
ALL built-in function 146 
allocating of storage 63-71 
allocating variables 19 
AND logical operations 146 
ANY built-in function 147 
AO (actual origin) 43 
AREA condition 70 
areas 

address 45 

control block 215 



areas (continued) 

descriptor 216 

locator descriptor 45,214 

storage management 70 
arguments . 

for conversion routines 13 8 

implementation 28 

library subroutines 28 
arrays 

as s ignment s 2 3 

descriptor 22,218 

FORTRAN 189-207,203 

I/O 131 

interlanguage communication 189-207 

interleaved 148 

locator 45 

of structures 22,4 8 

structures of arrays 22,4 8 

subscripts outside bounds 74 
ASSEMBLER option 205 
ASSEMBLER- PL/I communication 205 
attributes data 43, 50 
automatic variables 

addressing 19 

implementation in general 19 

in dump 187 

storage 6 3 



base addressing 

change of program base 35 

register usage 17,18 
base element 43 
based variables 

implementation 21 

in dump 187 

storage 63 
basic in-line conversions 142 
beginning of segment (BOS) pointer 58,65 
BIT data 

internal representation 137 

string assignment subroutine 
(IBMBBGF) 146 
block enable cells 75,26 
blocks 

activating 23 

inactive 28 

terminating 24 
BOOL built-in function 14 6 
bootstrap routines 28 

BOS (begining of segment pointer) 58,65 
bounds adjustable 43 
branching 26-27 

buffered consecutive files 109,94 
buffers 

contents in dump 167 

general 118 

pointers 119 

record I/O 106 
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buffers (continued) 

storage 63 

stream I/O 

pointers 119 
built-in functions 

arithmetic 145 

array handling 14 5 

condition 72 

DATE 149 

library subroutines 147 

mathematical 145 

stream I/O 131 

string handling 146 

structure handling 146 

TIME 149 
byte beyond the ISA 65 
byte, next available (NAB) 



65 



C format item DED 222 
CALL statement 25 
calling sequence 

interlanguage calls 205 

library 28 
calling trace 

following through dump 182 

obtaining 16 3 
CCB (channel control block) 149 
chain, free area 65-6 8 
chain, loaded module 60 
chain, open file 57,58 
channel control block 14 9 
CHARACTER data (how held) 137 
CHECK condition 81-84,50 
CHECK prefix 81 
checkpoint/restart facility 152 
CKPT macro instruction 152 
closing files 

CLOSE macro instruction 91 

explicit closing 101,93,109 

implicit closing 95 

library subroutine 101 
COBOL 

COBOL-PL/I communication 189-2 08 

interrupt 200 

option in ENVIRONMENT attribute 206 

structure mapping 189-207,205 
COLUMN format option 131,134 
common constants 35 
common control blocks 35 
common expressions, elimination of 31 
commoning 35 
communication 

between languages 189-207 

between routines 43-50 
compare aligned bit string subroutine 

(IBMBBBC) 146 
compare unaligned bit string subroutine 

(IBMBBGC) 147 
compilation 1 
compile time DED 50 

compiler generated subroutines 30,134 
compiler generated temporaries 11 
compiler options 

AGGREGATE 11 

COUNT 87,249 

deleted 11 

ESD 11 



compiler options (continued) 

FLOW 82-90 

LIST 11 

MAP 11 

OFFSET 11 

SOURCE 11 

STORAGE 11 
compiler output 9-3 
COMPLETION built-in function 152 
COMPLETION pseudovariable 152,156 
concatenate-character-strings subroutine 

(IBMBBCK) 147 
CONDITION condition 74 
conditions 

built-in functions 
general 71 

storage for values 77 
values in dump 182 

default enablement 73-86 

enablement 73 

main discussion 71-81 

name abbreviations in dump 163 

prefixes 72 

record I/O 106 

stream I/O 130-131 

values in dump 183 
consecutive buffered files 113,94 
constants 

commoning of 35 

general 16 

pool 16 
control blocks 

built-in functions 
default values 77 

commoning 35 

error handling 75-77 

formats and functions 213-261 

interlanguage communication 193 

locating in dump 186 

record I/O 96 

stream I/O 118 
CONTROL compiler option 11 
control format items 126 
control sections 9 
control variable of DO loop 30,33 
controlled variables 

control block 219 

in dump 185 

main discussion 19 

storage 63 
conversion 137-144 

basic 142 

CONVERSION condition 142,73,81 

hybrid 142 

in-line 141 

intermediate results 138 

invalid 14 2 

library subroutines 137,138,142 

multiple 142 

ONCA 143 

ONSOURCE 142 

stream I/O 119 
CONVERSION condition 142,73,81 
COPY option 131-132,135 
COUNT function 131 
COUNT option 87,249 
count table 87,249 
CSECT (control section) 9 
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current enable cell 75 



94 



DAM 
data 

aggregates (see aggregates) 

conversion (see conversion) 

internal representation 137 

interrupt 73 
DATA built-in function 149 
data directed I/O 124-125,51 
data element descriptor (DED) 

as argument for conversion routine 13 8 

for format items (see format element 
descriptor) 

formats 220-222 

general description 50 

in SIOCB 119 
data format item 125 
data interrupt 71 
data list matching 131 
data management buffer 119 
data sets 

definition 91 

interchange between PL/I and COBOL 206 
DATAFIELD built-in function 131 
debug option of PLIDUMP 163 
debugging using dumps 161-188 
decimal data format 137 
decimal divide interrupts 71 
decimal overflow interrupts 71,80 
DED (see data element descriptor) 
dedicated registers 17,18 
define the file control block (DTF) 94,95 

location 186 
DELAY statement 149 
descriptors 43-50 

aggregate descriptor descriptor 46,216 

area 46,214 

array 46,218 

data element (see data element 
descriptor) 

string 4 5 

structure 46 
DFB (see diagnostic file block) 
diagnostic file block 

format 224 

function 60 
diagnostic messages 84-87 
diagnostic statement table (DST) (see 

statement number table) 
director routines in stream I/O 115,133 
disablement of conditions 71 
disk files for restart 152 
DISPLAY statement 149 
DO loops 30 

modification of control variable 33 

register for control variable 17 
DSA (see dynamic storage area) 
dummy arguments in interlanguage 

communications 191 
dummy DSA 

address 59 

error handling 77 

introduction 4 
dummy ONCA 

chaining 77 

description 60 



180 



165 



(DSA) 
17 



182 



dummy ONCA (continued) 

introduction 55 
dummy PLIMAIN in IBMDPIR 55 
dump bootstrap module (IBMDKDM) 85 
dump control module (IBMDKMR) 85 
DUMP option in JCL 161 
dumps 

debugging with 161-188 

housekeeping information 

implementation 85 

library subroutines 84 

obtaining 161 

options 163 

stand alone 180 

trace information 
dynamic ONCB 77 
dynamic scope 72 
dynamic storage 63 
dynamic storage area 

address register 

associating DSA with block 

backchain in dump 180 

dummy 

address 59 

error handling 77 

error handling 77 

for main procedure in dump 184 

format 225 

forward chain in dump 29 

IBMDERR's DSA in dump 175 

initialization 55 

introduction 3 

prologue code 15 

uses 6 3 



E format DED 222 

ECB (see event control block) 

edit-directed I/O 125-130 

arrays 131 

buffer operations 125 

compiler generated subroutines 125 

control format items 126 

data format items 126 

FED 126 

format DED 126 

format list 126 

format option handling 131 

GET EDIT statement 125 

library director modules 131,133 

matching data and format lists 126 

non-matching data and format lists 126 

PUT EDIT statement 126 

X format items 126 
element, structure 43 
element, base 4 3 

elimination of common expressions 31 
elimination of unreachable statements 33 
enable cells 75,26 
enablement of conditions 

general 71 

summary chart 73,74 

testing for 82 
encompassing procedure (definition) 193 
end of extent, offset to (OEE) 70 
end of file 132,73 
end of segment pointer 65 
END statement 25 



Index 271 



ENDFILE condition 

library subroutine IBMDREF 108 

record I/O 106 

stream I/O 131 

summary information 73 
ENDPAGE condition 73,81 
entry data control block 227 
entry points 29 

addresses in dump 182 

conversion subroutines 138 

error handling subroutine 79 

executable program phase 9 

inter language communication 191 

library subroutines 37-44,28 

main procedure 9 
ENTRY statement in interlanguage calls 191 
ENVB (see environment block) 
environment 

at interrupt 72 

definition 2 

FORTRAN 191, 200 

interlanguage communication 191 

SORT 150 
ENVIRONMENT attribute COBOL option 20 6 
environment block 

format 228 

locating 186 

record I/O 96 

stream I/O 118 
EOFADDR routine 

stream I/O 131,118 
EOS (end of segment) pointer 65 
epilogue 24 
ERROPT routine 

record I/O 109 

stream I/O 118 
ERROR condition 72 

on- unit and dumps 170 
error handling during execution 71-84 

error code 75,184 

error handling subroutine IBMDERR 79-85 

event I/O 15 4,156 

FORTRAN 201 

identifying the erroneous statement 84 

interrupt in error handler 79 

messages 8 4,85 

record I/O 106-120 

stream I/O 131 
error identification 

address in dump 173 

ERROR on-unit 161 

in library module 185 

interrupt in error handler 171 

using dump in general 161-188 
error messages 84 
ESD records 

definition 9 

for conversion modules 138 

for LIOCS routines 91 

interlanguage communication 19 4 

reference listing 11 
established on-units 79 
EV (see event variable) 
even/odd register pairs 17 
event control block (ECB) 156 
event I/O 112,156 
EVENT option 154,112 
event table (EVTAB) 154,229 



event variables 154-159 

control block 230 

locating in dump 186 
EVTAB (event table) 

discussion 152 

format 229 
EXCP macro instruction 150 
executable program phase 4 
execute interrupt 71 
execution 9 

entry point 9 
exit table, SORT 149 
explicit open 106 

record I/O 106,96 

stream I/O 118 
exponent overflow interrupt 71,80 
exponent underflow interrupt 71 
exponentiation 146 
expressions 

common elimination of 31 

invariant 31 

movement out of loop 32 

redundant branching around 35 

simplification 24 
extent adjustable 19 

creation of temporaries 19 

in structures 147 
EXTERNAL data 21 
external reference, weak 39 
external symbol listing 11 



F- format records 134 

FAIS field in FCB 105 

FATM filed in FCB 105 

FCB (see file control block) 

FCBA field in FCB 119 

FCOP field in FCB 131 

FCPM field in FCB 132 

FED (format element descriptor) 

description 50 

format 222 

use in stream I/O 125 
FEFT field in FCB 108 
FEMT field in FCB 108 
FERM field in FCB 108 
fields, locating in dump 186 
file control block (FCB) 105 

FAIS field 105-119 

106,105,108 

118,119 

132 

131,132 

108 

108 

108 

fields for buffer operation 118 

format 231 

FREM field 118,119 

locating in dump 186 

record I/O 96 

stream I/O 118 
filenames 95 
files 

(see also data sets) 

chain open 58 

declaration with COBOL option 206 

definition 91 



FATM field 
FCBA field 
FCOP field 
FCPM field 
FEFT field 
FEMT field 
FERM field 
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163 



101,109 
101 

94 
103 



57,74,81 



files ( continued) 

information in dump 

open file chain 58 

record I/O 

declaration 95 
explicit closing 
explicit opening 
filename 95 
implicit closing 
implicit opening 
types 94 
FINISH condition 
fixed point data 

binary 137 

decimal 137 

DED 221 

divide interrupt 71,79 

overflow interrupt 71,79 
FIXEDOVERFLOW condition 73,71,80 
floating point data 

binary 137 

conversion to character string 142 

decimal 137 

DED 221 

divide interrupt 71 

underflow interrupt 80 
floating point registers 

saving 79 

usage 18 
FLOW compiler option 87 

(see also flow statement table) 

library subroutine IBMDEFL 87,89 
flow of control 23 
flow statement table 87-94 

format 234 
format DED (see format element descriptor) 
format element descriptor (FED) 

description 50 

format 222 

use in stream I/O 125 
format items 126 
format list matching 131 
format option handling 131 
formatting modules in stream I/O 135 
FORTRAN-PL/I communication 189-208 

FORTRAN interrupt 200 

FORTRAN option 191 
free area chain 59 
free decimal format 141 
freeing storage 63 
freeing variables 21 
FREM field in FCB 119 
FST (see flow statement table) 
function reference 25 
function values, on- condition 6 



general registers (see registers) 
GET DATA statement 

CHECK condition 82 

main discussion 122 

symbol tables and symbol table 
vectors 51 
GET EDIT statement 125 
GET LIST statement 122 
GET macro instruction 91 
GOTO statement 

from SORT 150 



GOTO statement (continued) 
main discussion 26 



hardware interrupts (see program check 

interrupts) 
hexadecimal dump 167,163 

hexadecimal dump subroutine (IBM.DKDD) 87 
hybrid conversion 142 



IBMBAAH 


146 






IBMBAIH 


145 






IBMBAMM 


147 






IBMBANM 


146 






IBMBAPC 


146 






I3MBAPF 


146 






IBMBAPM 


146 






IBK3ASC 


146 






IBMBASF 


146 






IBMBAYF 


146 






IBMBBBA 


146 






IBMBBBC 


146 






IBMBBBN 


146 






IBMBBCI 


147 






IBMBBCK 


147 






IBMB3CT 


147 






IBMBBCV 


147 






IBM3BGB 


147 






IBMBBGC 


147 






IBMBBGF 


147 






IBMBBGI 


147 






IBMB3GK 


147 






IBMBBGS 


147 






IBMBBGT 


147 






IBMBBGV 


147 






IBM3ILC1 


(interlanguage root 


control 




block) 


195,235 






IBMBMXL 


146 






IBMBMXS 


146 






IBMBMXW 


146 






IBMBMXY 


146 






IBMBMYK 


146 






IBMBMYS 


146 






IBMBMYX 


146 






IBMBMYY 


146 






IBMBPAF 


21 






IBMBPAM 


70 






IBMBSAI 


135 






IBMBSCI 


135 






IBMBSCO 


135 






IBMBSCV 


143 






IBMBSFT 


135 






IBMBSFo 


135 






IB MBS PI 


135 






IBMBSPO 


135 






IBMBSTAB 


122 






IBMDEFL 


8 7-94 






IBMDERR 


79-85 






IBMDESM 


84 






IBMDESN 


84 






IBMDIEC 
I3MDIEF 


197 

200 






IBMDIEP 


202 






IBMDJDS 


150,159 






IBMDJDT 


149 






IBMDJDY 


149- 






IBMDJTT 


149 
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IBMDJWT 


156,155 


IBMDKCP 


152 


IBMDKDD 


85 


IBMDKDM 


85 


IBMDKMR 


85 


IBMDKST 


150 


IBMDOCA 


108,101 


IBMDOCL 




record I/O 


implicit opening 101 


record I/O close 109,101 


record I/O open 100-117 


stream I/O 118 


IBMDOPA 


101 


IBMDOPB 


101 


IBMDOPC 


101 


IBMDPEP 


86 


IBMDPES 


86 


IBMDPGR 


68 


IBMDPII 


56 


IBMDPIR 


56 


IBMDPJR 


57 


IBMDRAW 


102 


IBMDRAX 


102 


IBMDRAY 


102 


IBMDRAZ 


102 


IBMDRBW 


102 


IBMDRBX 


102 


IBMDRBY 


102 


IBMDRBZ 


102 


IBMDRCY 


102 


IBMDRCZ 


102 


IBMDRDY 


102 


IBMDRDZ 


102 


IBMDREF 


102,108 


IBMDREX 


102,106 


IBMDREZ 


102,106 


IBMDRIO 


109-112 


entry 


points 102 


paramenter list 96 


IBMDRJZ 


102 


IBMDRKZ 


102 


IBMDRLZ 


102 


IBMDRQX 


102 


IBMDRQY 


102 


IBMDRQZ 


102 


IBMDSCP 


131 


IBMDSCV 


131 


IBMDSDI 


134 


IBMDSDO 


134 


IBMDSED 


134 


IBMDSEI 


125,131,134 


IBMDSEO 


125,134 


IBMDSII 


133 


IBMDSIO 


133 


IBMDSIS 


132,133 


IBMDSLI 


133 


IBMDSLO 


134 


IBMDSOF 


135 


IBMDSOU 


135 


IBMDSOV 


135 


IBMDSPL 


131,135 


IBMDSTF 


135 


IBMDSTI 


135 


IBMDSTU 


135 


IBMDSTV 


135 


IBMDSXC 


125,134 


IBMGJWT 


159,152 



IELCGBB 31 

IELCGBO 31 

IEICGCB 31 

IELCGCL 31 

IELCGIA 31,131,134 

IELCGIB 31,134 

IELCGMV 31 

IELCGOA 31,134 

IELCGOB 31,134 

IELCGOC 31,131 

IELCGON 31 

IELCGRV 31 

IIBMDREY 102,106 

implicit close in record I/O 109,94 

implicit open 

record I/O 103 

stream I/O 118 
in-line conversion 139 
in-line record I/O 109,91 
inactive event 156,152 
INDEX built-in function 146 
indeking interleaved arrays 145 
initial storage area (ISA) 63,55 
initialization 55,56 

FORTRAN 200 

stream I/O subroutines 133 
input/ouput control block 

format 235 
input/output 91-135 

instruction associating with module 181 
INTER option 191,200,201 
interlanguage communication 189-206 

aggregate arguments 189-207,46 

arrays 203 

assembler 205 

ASSEMBLER option 205 

basic rules 191 

COBOL option of the environment 
attribute 205 

control blocks 195 

entry point declaration 191 

environment changes 191 

interrupt handling 191 

interrupt in COBOL 200 

interrupt in FORTRAN 46 

interrupt in PL/I 203 

NOMAP option 205,191 

NOMAPIN option 205,191" 

NOMAPOUT option 205,191 

principles 32 

root control block (IBMBILC1) 195,238 

storage 205-208 

structures 189-207,205 

SYSLST 197 

VDA 195,235 
interlanguage VDA 238,195 
interleaved arrays 145-147 
internal form of data 137 
interprets ve code 

for GOTO 28 

need for 4 
interrupt handling 71 

COBOL 200 

event I/O 156 

FORTRAN 201 

interrupt levels 71 

interrupt save area 79 

library subroutine (IBMDERR) 79-85 
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interrupt handling (continued) 

program check 79 

return 81 

software 80 
interrupt identification using dump 

at address not in linkage editor 
map 1 85 

in error handler 171 

in library modules 185 
invariant expressions 32 
invert-aligned-bit-string subroutine 

(IBMBBBN) 146 
IOCB 

format 235 
ISA (initial storage area) 6 3,55 
ISA, byte beyond 65 
ISAM (indexed sequential access method) 94 



KD (see key descriptor) 
KEY condition 73 
key descriptor 239 
key descriptor (KD) 100 
key variable 91,100 



label 

control block 240 

labelled statements 26-27 
label data control block 240 
label variables 27-28 
labelled statements 26-2 8 
last in/first out (LIFO) storage 2,64-68 
LEAVE option 102 

lengths of library modules 264-268 
levels of interrupt 72 
library subroutines 37 

alphabetical list with lengths and 
function 263-267 

arithmetic 145 

array handling 145-147 

calls 28 

computational 145 

conversion package 137 

entry points 29 

in record I/O 101 

in stream I/O 133-14 6 

interrupt in 

finding module name 187 
programmer action 184 

interrupt in transient module 185 

INTRODUCTION 4 

MATHEMATICAL 145 

naming conventions 37,29 

register usage 18 

string handling 146 

structure handling 147 

workspace 39 
library workspace (LWS) 

description 39 

format 241 

locating 187 
LIFO (last-in/first- out) storage 63-7l 
LIMSCONV option 130 
LINE format option 131 
link- editing 55 
LIOCS (logical input/output control system) 

routines 91,108 



LIST compiler option 11 
list-directed I/O 120,122 
listings 11 
loaded module chain 60 
LOCATE statement 91 
locators 43-50 

aggregate locator format 217 

area locator format 214 
loqical input output control system 

(LIOCS) 91,108 
logical operation subroutines 146 
loops 3 

modification of control variable 33 

movement of expressions out of 32 



main procedure 

DSA in dump 180 

entry pcint 9 

in interlanguage communication 193 

no main procedure 55 

termination of 56 
major free area 64,65 
map of static storage 11 
merge facility 150-153 
messages, diagnostic, implementation 

of 84-87 
modification of control variable 33 
movement out of loop 32 
multiple conversions 142 
multiple event waits 156 
multiplication, optimization of 33 
multiplier array 22 
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37-42,29 
pointer 65 



NAB (next available byte) pointer 

locating 187 
NAME condition 131,73 
naming of library modules 
next available byte (NAB) 

locating 187 
NOCHECK prefix 81 
NOCONVERSION prefix 131 
NOMAP option 191,20 5 
NOMAPIN option 191,205 
NOMAPOUT option 191,205 
non-LIFO storage 4 , 63 , 66 
NOOPTIMIZE 31 
null on-unit 80 



object module 9 

object program listing 12,11 

OCB (see open control block) 

OCCURS (COBOL) 205 

OEE (offset to end of extent) 70 

offset 

listing 11 

on- cells 75,80 
ON CHECK statements 81 
on communications area (ONCA) 

description 77 

dummy 55,60 

format 242 
ON control block (ONCB) 243 

description 75 

locating 187 
ON statements 77 
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on- code 75 

in dump 182 
on-units 71-82 

GOTO only 28 

in event I/O 156 
ONCA (see ON communications area) 
ONCB (see ON control clock) 
ONCHAR 142, 81 
CNSOURCE 142,81 
open control block (OCB) 

format 244 

function 96 

locating 187 
open file chain 58 
OPEN macro instruction 91 
opening files 

explicit open for record I/O 100 

implicit open for record I/O 94,103 

stream I/O 118 
operating system interfaces 150,159 
operation interrupt 

analysis code 60 
optimization 31-36 

branching around redundant 
expressions 35 

commoning 35 

effect in conversion 137 

effect of common expressions 31 

elimination of unreachable 
statements 33 

modification of loop control 
variable 33 

rationalization of branches 35 

simplification of expressions 33 
OPTIMIZE (TIME) 31 
OPTIONS attribute 191 
options of PLIDUMP 163 
OR logical operation 14 6 
output (see input/ out put) 
output, compiler 9-3 
OVERFLOW CONDITION 73,71 
overflow routine, stack 58,70 



packed intermediate decimal format 139 
PAGE format option 131,135 
pairs , even/odd, register 17 
parameter lists 

address register 17 

contents in dump 185 

for conversion routines 138 

main discussion 29 
partition dump 163 
partition save area 180 

password for deleted compiler options 11 
PICTURE data 

DEDs 221 

FEDs 222 

internal representation 137 
PIK (program interrupt key) in dump 171 
PL/ I environment (see environment) 
PL/I -ASSEMBLER communication 205 
PL/I-COBOL communication 189-207 
PL/I -FORTRAN communication 189-207 
PLICALLA 57 
PLICALLB 57 
PLICKPT 152 



PLIDUMP facility 

how to obtain dump 161-165 

how to use 163 

implementation 85 

options, list of 163 
PLIFLOW 87,9 
PLIMAIN 55,9 

dummy in IBMDPIR 55 

format 245 
PLISA 197 
PLISRT 150 
PLISTART 55 

format 246 

initialization 55-60 
PLITABS 120 
pointer data 21 
pointers 

BOS 65 

buffer pointers, stream I/O 119 

COPY option 131 

DSA 17 

EOS 65 

FCBA 119,131 

FCPM 131 

FREM 116 

NAB 65 

TCA 17 

TISA 65 
POLY built-in function 146 
prefixes 72 

principal procedure, definition 193 
PRINT files 120 

privileged operation interrupt 71 
PRCC statement in interlanguage calls 191 
PROCEDURE BASE 15 
PROD built-in function 147 
program base 17,35 
program check interrupts 71,79 
program control section 9,16 
program flow 23 

program interrupt key (PIK) in dump 180 
program management area 56-61 
program status word (PSW) 

locating in dump 171 

using to identify interrupt 171 
program text statements, number of 11 
program tuning, report option 168 
prologue 23 
protection interrupt 71 
PSW (see program status word) 
PUT macro instruction 91 
PUT statement 120 



Q option of PLIDUMP 163 



RD (see record descriptor) 

READ macro instruction 91 

READ statement 91 

REAL ENTRY 15 

recompilation to obtain dump, avoiding 22 

RECORD condition 73 

record descriptor (RD) 

discussion 100 

format 247 
record I/O 91-135 

control blocks generated 97, 96 
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record I/O (continued) 

control blocks generat (continued) 
in-line I/O 109 

error handling 106 

in-line 109-112,94 

interface routine (IBMDRIO) 96,109 

library call 94 

library routines 100-110 
list of 101-102 

raising conditions 106 

record I/O 109 

implicit opening 109 

summary of library usage 100 
record variable 91,100 

redundant expressions, branching round 35 
REFER option 46 
registers 

contents in dump 28 

save area in dump 183 

summary 184 

usage 17-31 
relative virtual origin (RVO) 43,46 
release identification 59 
relocatable object module 9 
REPEAT built-in function 147 
REPLY option 149 
report option of PLIDOMP 167 

using for program tuning 168 
required procedure, definition 193 
resident library 37 

alphabetical list of modules with 
lengths 263 
restart (checkpoint restart) facility 152 
return code 

PL/I 81 

SORT 150 
return from interrupt 81 
RETURN statement 25 
REVERT statement 77 
REWRITE statement 94 
RLD records 9 
RVO (relative virtual origin) 43, 46 



SAM 94 
save areas 

calling routine 58 

IBMDPGR 60 

IBMDPIR 60 

partition 25 

registers in dump 184 

system 81 
SAVE field in SIOCB 118 
SCNT field in SIOCB 118 
scope 72 

segments (see storage) 
SETIME macro instruction 149 
SFCB field in SIOCB 118 
SFLG field in SIOCB 118 
significance interrupt 71 
simplification of expressions 33 
single event waits 159 
SIZE condition 73,71,80 
SKIP format option 131,135 
SLD (see string locator descriptor) 
SNAP 80,85 
SOCA field in SIOCB 118 



software interrupts 

definition 71 

main discussion 80 
SORT exit 150,28 
sort merge facility 150-152 
source 

address, during stream I/O 118 

DED address, during conversion 138 

definition 115 
source program listing 11 
source records, number of 11 
spanning record boundaries (stream 

I/O) 116 
specification interrupt 71 
SRTN field in SIOCB 118 
SSDD field in SIOCB 118 
SSRC field in SIOCB 118 
SSTR field in SIOCB 118 
stand alone dump 180 
standard system action 

action taken 74 

definition 71 

when taken 77 
statement frequency count table 

format 249 
statement number 

in messages 85 

of error in dump 182 
statement number table (DST) 

format 251 
statements, elimination of unreachable 33 
static backchain 

in dump 180 
static base address 17 
static internal control section 16 
static 

contents 16 

listing 11 

map 11 

scope 72 
static variables 21 

locating 185 
STATUS fun ction/pseudo variable 156 
STDD field in SIOCB 118 
storage 

automatic 19 

chart showing principal contents 211 

interlanguage communication 19 5 

main discussion 63-72 

management routine 68 

requirements listing 11 

segments 65,70 

sort merge facility 150 

static map 11 

temporary 17 
stream I/O 115-135 

access method 118 

buffer usage 118 

built-in functions 131 

conditions 131 

conversion 118 

COPY option 132,131 

COUNT function 131 

DAT AFIELD function l3i 

define the file control block (DTF) 118 

director routines 115,132,135 

end of file 118 

error handling 131 
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stream I/O (continued) 

external conversion director 
modules 120,134 

file opening 118 

format items 126 

format lists 126 

format options 131 

formatting modules 133,134 

implicit open 118 

initializing modules 133 

library usage summary 133 

LIOCS routines 115 

ONCHAR 131 

ONSOURCE 131 

spanning record boundaries 115,118 

stream I/O 

general 117 

transmitter modules 118,133 
stream I/O control block 

discussion 118 
stream I/O control block (SIOCB) 

format 250 
stream I/O opening 118 
STRG field in SIOCB 118 
string descriptor 252 
string locator/descriptor 45,252 

subroutine 147 
strings 

adjustable 145 

DED 221 

FED 222-223 

length 46 

library subroutines 133,147 

locator descriptor 45 

STRING function/pseudovariable 147 

STRING option 132-144 

STRINGRANGE condition 74,147 

STRINGSIZE condition 74 

unaligned 146 

varying -length 137,146 
structure descriptor 253 
structures 

array of structures 22,4 8 

COBOL 189-207,206 

descriptor 45 

element definition 43 

interlanguage communication 205 

locator (aggregate locator) 46 

main discussion 22 

mapping 46,147 

of arrays 22,48 

structure descriptor descriptor 46 
STXIT macro instruction 56 
subroutines, compiler generated 30,125 
subroutines, library (-see library 

subroutines) 
SOBSCRIPTRANGE condition 74,81,161 
SUBSTR built-in function 147 
SUM built-in function 147 
symbol table (symtabl 51-67 

format 254 
symbol table element list (see symbol 
table vector) 
symbol table vector 51 

format 256 
SYSLST in interlanguage calls 195 
system action, standard 

action taken 74 



system action, standard (continued) 

definition 71 
system dumps 

initiation 79,85 

interpretation 171 
system interfaces, miscellaneous 147-159 
system save area 79 



tab table 120 
target 

address, in conversion 138 

address, stream I/O 118 

DED address, conversion 138 

definition 115 
task communications area (TCA) 

address register 17 

appendage (TIA) 59 

format 257 

GOTO code in 59,28 

introduction 2 

major discussion 58 

offsets for library subroutine 
addresses 3 
TCA (see task communications area) 
TCA appendage (TIA) 

format 259 
TECB (timer event control block) 149 
temporary variables (temporaries) 

address register 17 

description' 19 

storage for 63 
TERA field in TCA 59 
terminating blocks 24 
termination of program 

after dump 163 

after interrupt in error handler 79 

general 56 
TEST field in TCA 87 
TIA (TCA appendage) 

format 260 

main discussion 59 
TIME built-in function 149 
timer event control block (TECB) 149 
TISA (address of byte beyong ISA) 65 
TITLE option 102 
TLFE field in TCA 59 
trace 

FLOW option 87 

information in dump 22 

obtaining in dump 165 
transfer of control 23 
transient library 37 

alphabetical list of modules with 
lengths 266 
translate and test table in TCA 77,60 
TRANSLATE built-in function 147 
transmission statement 

definition 91 

in record I/O 94 
TRANSMIT condition 131 
transmitter modules 

stream I/O 118,134 
TXT records 9 



D- format records 135 
unaligned strings 145,147 
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UNDEFINEDFILE condition 73 
UNDERFLOW CONDITION 71,73 
UNLOAD option 102 
unqualified conditions 73, 74 
user exits (sort) 150 



V- format records 135 
variable data area (VDA) 63 

inter language communication 195,238 
variables 

adjustable (see adjustable extents) 

area (see areas) 

automatic (see automatic variables) 

based (see based variables) 

controlled (see controlled variables) 

entry 227 

event (see event variables) 

label 26-27,240 

map of offsets 12 

locating in dump 187 

pointer 21 
varaibles offset map 12 
varying length strings 

effect on library usage 147 

internal representation 137 
VDA (see variable data area) 
VERIFY built-in function 147 
version identification 59 
virtual origin (VO) 22 
VO (virtual origin) ,2,2 



WAIT macro instruction 152 

WAIT statement 152-159,112 

WAITF macro instruction 150 

WAITM macro instruction 150 

weak external reference (WXTRN) 39 

work registers 17 

workspace, library (see library workspace) 

WRITE macro instruction 91 



X format items 131,134 



ZCTL (zygo-lingual control list) 195,197 

format 261 
ZERODIVIDE condition 73,71,80 
zygo-lingual control list 195,197 

format 261 
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